Comments on: Minimizing Documentation

By: GIS Application Designers: We Should All ‘KISS’ « GeoChalkboard

GIS Application Designers: We Should All ‘KISS’ « GeoChalkboard — Thu, 17 Dec 2009 22:42:11 +0000

[...] out! And I’ll resist the temptation to sharp stick ESRI on this issue! Tip of the hat to I’d Rather Be Writing. …..every time you add something to an interface, you should take something away. Keeping the [...]

By: Robyn

Robyn — Thu, 10 Dec 2009 21:45:44 +0000

I start out with a one-page guide, and by the time that all the reviewers and approvers get done editing, I have 20 pages! How do I reign in everyone, when their opinions are very strong and they get indignant when you don’t incorporate their edits?

By: Tom Johnson

Tom Johnson — Fri, 20 Nov 2009 17:19:36 +0000

Rob, thanks for your comment. I think the interaction between Support and Documentation is a key strategy that every doc dept should be pursuing.

Re the screenshot of your company’s product — you made me laugh. Yes, it’s too common of a scenario.

By: Rob Allison

Rob Allison — Fri, 20 Nov 2009 12:03:28 +0000

Firstly Tom, how did you obtain that screenshot of my company’s product?

I have just forwarded this topic to the System Designers and my Technical Author colleagues as it beautifully puts across points I have been making for some time.

Thanks for backing me up so succintly.

Our product has context-sensitive help and I am currently single-sourcing using XML base files to output HTML for the help and .pdfs for training manuals.
I am trying to push for more interaction between our Support team and documentation so we can publish topics which specifically meet (and reduce) support calls.

Anyway – thanks for confirming my own direction is not too far from really informed thinkers in this arena!

Keep up the good work sir!

Rob

By: Tom Johnson

Tom Johnson — Wed, 18 Nov 2009 19:23:05 +0000

Thanks Graham. This topic is also apparently a growing trend (see my poll in the right sidebar).

By: Graham

Graham — Tue, 17 Nov 2009 09:26:02 +0000

This is one of the best reads I have had in weeks. Thanks.

By: Dan

Dan — Mon, 16 Nov 2009 04:14:07 +0000

good post!
its not a fair comparison but gets the message across.
Unfortunately, for ‘Your Company’s APP’, which appears to be a data entry application (majority of most bread and butter programs like these) – it’s bound to have lots of entry fields and little widgets.

By: Rengaraman

Rengaraman — Thu, 12 Nov 2009 06:10:41 +0000

Another good post Tom. I feel, sometimes it is the client who decides how much information he wants. If our client is a novice user, little informative documentation won’t be helpful. Again, the TWs’ will be blamed of not providing necessary info along with the product.

By: Ivan Walsh

Ivan Walsh — Thu, 12 Nov 2009 05:32:43 +0000

Is less always more?

No, less is less.

What people mean (I assume) is that less text/features etc will produce more results. This isn’t always the case. Imagine if medical companies did less lab testing? Would you really buy their products? If car companies did less, would you feel safe?

The trend towards shorter docs, imho, is due to several factors: time-poor readers, more churn in the document lifecycle, expense of updating long docs and cut-backs in tech doc depts. If you don’t have the writers, you can’t write the docs…

Looking into my crystal ball, I feel that we’re moving towards ‘real-time’ information, i.e. the end of paper manuals (with the possible exception of sop and field documentation).

Technical writers of the future will coordinate the distribution of material, spending time synching content, aligning it to new releases and less on actual text generation.

From a snow-covered Beijing.

Ivan

By: Arnold Burian

Arnold Burian — Thu, 12 Nov 2009 00:42:13 +0000

Those are great tips! And if you needed to sell the reasoning behind this, just factor in the cost of localization. Every word has a cost, multiplied by the number of languages you have to support.

Great advice!