First Drafts


Question: How polished-looking does my first draft need to be?

This is an important question, now that documentation has not only moved online, but has migrated into Wiki-like systems where you can have miles of empty placeholder topics, maybe 10 of which are actually populated – and it’s all in your live system because it’s always a work in progress. There’s no way a user can tell from the listings which topics actually have data in them.

Some reviewers will latch on to trivial aspects of formatting or usability instead of focusing on what is said. First impressions can count. Higher-ups are more likely to react on first impressions, so forcing them to click through miles of empty topics isn’t the greatest.

“Learn what finished work look like and only show yours when it looks the same way,” advises my little book on business wisdom.

With all the push for online documentation, real operability is as important as formatting. If it’s your first demo, make it a working demo that actually works. You can suggest a few search terms, but those searches better yield something that looks like the real thing. Showing someone a Powerpoint of a UI design is like showing people a picture of a Tesla and assuring them that it’ll be fun to drive.

Google Docs doesn’t seem to have as much of a problem with empty topics, but there’s not much in the way of information hierarchies. You can’t get an overview of what’s in there, just jump from page to page. Unless they’ve improved it recently, there isn’t even an expandable navigation tree viewer, like you get in any normal file system. There’s no way to organize all that information other than keyword searches.

Wikis and Confluence seem to be the big shit these days. Mainly because you can have your developers write your documentation and cut out the writers altogether. I personally don’t like to deliver these interim systems with empty topics presented on the same level as completed ones. It looks half-assed. I would want to hide the empty items until there’s something to show.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s