Monday, October 01, 2012

Stumbled upon: Write the Freaking Manual

I stumbled upon the thread "WTFM: Write the Freaking Manual" triggered by the following blog post

I would recommend to follow the thread (which already contains more than 200 thoughts) in case you want to understand:
  • the different views of the developers
  • the different views of users of a certain software
  • the different views of tech writers
I also had discussions with companies creating software products what needs to be documented, is it possible to create a software product which doesn't required additional documentation because of "intuitive usability" etc.

The answer is easy and difficult at the same time:

You have to deliver relevant information for your audience.

This means you have to understand:
  • What is your audience?
  • What is relevant?
 And always keep in mind that  "Your user does not have the same context compared to you".


If you develop a software infrastructure should support other developers to do their job faster you should deliver:
  • orientation for your user (which tasks does the library support)

    the concept of all major parts of your framework from top to down
    => basic overview of all implemented concepts and than describe each concept

    good example is provided by IBM for their ICU library (
    This library isn't very trivial but you have well described concepts for all components of the library.
  • how-to setup
    provide how-to to setup the software for initial use
  • how-to use
    provide as many code samples / demos / real working code for the operation of your user
    e.g. by providing your well-documented unit-test library.

How can you identify which information your audience needs? 

You have to understand their daily operation with your software and all questions which cannot be answered by the software itself without additional information in a short amount of time.

If you identified those areas well the resulting documentation will add value to the software and will increase the audience using your software.