Wikis: The Solution for The Writer's Problem? (part 2)

Before we begin, a bit of appreciation for YouTube's "transcription feature."

Because I have a hard time processing spoken words, I find it so much easier to understand what I read.  I just recently discovered YouTube's "transcription feature," and I appreciate that help something fierce.

Now, about wikis as the solution to the writer's problem, using Ted Nelson's talk about the writing problem as a reference.


The Writer's Problem: Organizing Ideas is Hard


(Well, writer in general, but with a "software documentation" technical writing mindset ...)

To me, organizing ideas (or concepts, or information of any kind) is hard because of a struggle with issues related to structure:

  • writing delay caused by a need to first settle on a structure for the ideas when, more than likely, not all ideas are yet known
  • value loss resulting from however many  "contextual views" (i.e. Nelson's "threads of interconnected ideas") hacked away while adopting a structure that, likely, can only present one "contextual view" of those ideas
  • re-structuring effort, because an initially chosen structure at some point does not accommodate new ideas and/or a need for a different "contextual view"
  • management nightmare: multiple structures, duplication of ideas and synchronization of changes
    • whenever a new "contextual view" becomes necessary, we wind up needing an additional structure
    • we wind up with copies of the same ideas repeated in multiple structures, and we change anything about an idea, we have to somehow keep the copies (in other structures) in sync

An Example Story


John asked his team of programmers to each create a document containing his/her job description, and to store each document in a shared folder.

Time goes by, and one of the programmers suggests: since we have so many applications, and each programmer supports certain applications that some other programmers also support ... Wouldn't it make more sense for us to instead create one document per application, and include in each document information about each programmer (and specific responsibilities) who supports the related application?

John and his team decide to discuss "structure" in a meeting the following week.

So writing gets delayed as the team tries to figure out which structure to adopt.

The dilemma faced: the choice of a structure will provide one "contextual view", but will result in the loss of another "contextual view".

Well, the team may choose to create two structures, one structure for documents about job descriptions, and one structure for documents about applications:
  • Should "Moe" resign, the team has that job description ready for placing in a job ad
  • Should there be an issue with some application, the team has a document that shows what programmers know that application
Of course, we not have information duplicated across the structures:
  • Moe, like every one of his teammates, has a document for his job description which describes the applications he works on.
  • Each application has a related document which includes information about each programmer who supports that application
So whatever information Moe has in his job description document, any section in that job description related to whatever application also exists in the document related to application.  From a document management perspective: yuck.

Enter Wiki


Forget about structure.  Just get to writing, and figure out structures organically, if and when you need them.

In a wiki, every page is like a writer's file card: each page, like a file card, represents an idea that is sufficiently complete on it's own and is a first class citizen (there is no hierarchy or wiki pages.)  With page "links", a page can have a connection to any other pages.

To build structure as needed, just know wiki features that provide what I consider as structure on steroids:

  • Page links.  Any page can have a page link to any other page.
  • Back links.  Usually an automatic feature and available on every page, provides links to all of the pages that reference (i.e. have links) to the currently viewed page.
  • "Index" pages.  These are just wiki pages that display a list of page links for however many pages that have some logical commonality.
  • Page "Includes".  Rather than linking from one page (say page "A") to some other page (say page "B"), we can actually include the contents of some other page ("B") directly into a page ("A")
  • Super-mishmash.  Although any one page can only have one list of back links, a page can have have any combination and number of page links and page includes (of any kind of page), intermingled with actual content in the same page


In Conclusion, for Now ...


Give Ted Nelson's talk about the writing problem a listen.  To me, everything he talks about, I can't help but think that it screams out:  Wiki !!!

With this post, I am setting the stage for future posts to discuss this oh-so-simple, yet amazingly powerful, tool with the quirky name.  To me, wikis are intertwingularity tamers, and I'll do my best to make the case !

In the meantime, cheers !