English 421: Technical Writing

A Recipe for designing usable documentation

This article provides a good summary for how a usable document is created and the important criteria that the document must contain. The authors first point is that the Document must think the way that you do... That is, the document must be easy to follow and should be able to conform to your understanding of the software/whatever that it is being written about. It is important that the reader knows how to follow through the hierarchy of steps or summations that the document encompasses. The second point the author brought up is that the documentation should "Match the product"  meaning once you hit a snag or have a question you know precisely where to turn in your documentation, and THAT exact place where you are having an issue is at least indexed in some way, clearly so that the user will know that this is the right place to be seeking help.  Also the author talks about using synonyms so that if the user's terms do not exactly match the terms of software or whatever service is being documented, they can easily understand what is going on in perhaps their own terms.  The next step states that the documentation should be "Short and sweet -yet still complete". This step has a lot to do with being aware of who your audience is and providing the proper amount of information to this crowd without overdoing it and walking through ever miniscule step or talking over their heads and just creating a worthless usability document.  The writer also suggests offering places where the user can get more specific help on a topic.