Documentation should be in a wiki

Posted by Chris on October 10th, 2007 filed in programming

Let me repeat that.  Documentation should be in a wiki.

Here is how things are done in my corporate world.  For keeping track of versions, other info, etc we have a series of Excel files kept either on a shared network drive or in The Worst Software Ever (Lotus Notes).  Which either means

A)

1- Finding the excel file link or browsing the shared folders looking for it

2- Opening it and hoping it’s not in use (and thus locked)

2a- If locked, try to remember to make the change later (and forget)

3- Editing the file, trying to find the  appropriate area and fill in a lot of non-friendly fields

or

B)

1- Opening TWSE and waiting for it to open.

2- Trying to find the link you saved to where the file is because you can’t search in TWSE

3- Opening a file which involves multiple clicks, editing steps, etc

4- Repeating the steps from above with the actual file.

Compare this with a wiki.

1- Open the wiki

2- Search for your thing you are documenting (or going to the bookmark even)

3- Clicking “Edit”.

4- Changing the page which can be any format that makes sense.

Note also that with some customization of open source wiki software, you could also either automagically populate a main status page from the wiki or from the thing you’re documenting directly.  This could also be done for versions, etc.  Summation then:  automatic populating of things is of course best, but short of that whatever you’re working on should be A) searchable, and B) very easily editable.

Leave a Comment