What’s better for documentation than a document?

5jets

People are afraid of big documents.  They are.  So many people have struggled emailing around documents for years, and it’s a terrible platform for collaborating with a team.  There is a better way to share the load.

I like to ask groups “Raise your hand if you have written a document.  OK, raise your hand if you’ve worked on a document with 3 or more people.  OK raise your hand if it was awful.”  Sure, in some systems you can track the changes, but it has nothing on using a WIKI.  WIKIs are great because:

  • You can see when and who made any changes
  • Reverting back is simple.
  • You don’t have to approve changes.
  • Simple things like minor corrections are very easy.
  • Making links to new documents is simple.

My favorite point is the last one.  Making links to information is really easy.  Have you ever randomly browsed around the Internet before?  Of course!  You click on things that interest you.  You find information and if you want more, you click.  Scrolling through giant documents looking for the information they need is the opposite of how most people like to discover information.

Apply this effectively

  • Start with content, and build the structure after – You don’t have to begin with any particular section, just start making pages of content.  Build a page at the end for structuring all your pages.  I find that most people try to build the structure first, and end up with pages with very little content.  Structure it later.
  • Show what’s not done clearly – When working on a document, you wouldn’t share it when it’s 10% done, but when using WIKI pages, you can send a link to what can be reviewed right away.  My favorite way to show what’s not done is to call it out with my name, date, and comment.  LITTLEPM Jul 1, 2020: Will need content from Marketing group for this section…
    Note of course people could look at the WIKI history to see who added that comment and when, but you’re making it really clear.  When working with many people on content, I like to call out who needs to add what to the various sections, and you don’t need to pass a file around – people just need to look for their name, and add in the appropriate content.
  • Encourage changes – This is hard for some people to allow others to just add.  In organizations I’ve worked in/with, people really struggle with the attitude of “oh that’s wrong, I’ll just fix it” particularly when people have used Tracked Changes in Word for years.  Using Word people figure that it’s someone else’s document, so they’ll just create more work for the author by adding tracked changes or comments.  Save everyone time!  Just fix it!

WIKI Services and Products

  • Trac – http://trac.edgewall.org
  • MediaWiki – https://www.mediawiki.org/wiki/MediaWiki
  • PmWiki – http://www.pmwiki.org/
  • Wikka – http://wikkawiki.org/
  • Wikidot – http://www.wikidot.com

TOPICS