5

I am writing a lot of software and I feel that writing good documentation is very difficult. Since I am not aware of any structured theory about software documentation I started to organise my knowledge in this field and hope that doing this will help me to break down information in sensible units and organise documentation efficiently.

First, I would like to make a complete list of relevant concepts, that I will investigate in other questions.

Which concepts are useful or relevant when describing user documentation? How does these concepts interact with each other? Is there any methodology I can use to analyse my software and devise a pertinent documentation strategy?

I identified the following concepts:

  • Information categories like recipes (“how do I…?”), references (like UNIX man pages) or expert knowledge.

  • User role like normal user, power user, system administrator and any other roles that the system defines like security officer, data officer, etc.

  • Medium like a hardcopy manual, contextual help, editable wiki.

These concepts interact one with the other and lead to a variety of questions: When is it useful to write a handbook for each role? What should go in hard copies and what in the on-line reference? When is it useful to run a wiki gathering “recipes”? With these examples, I hope I could provide a useful explanations of what I understand under “concept” and “interaction” in my questions.

Michaël Le Barbier
  • 2,025
  • 14
  • 25
  • possible duplicate of [Good references for End User documentation examples and advise](http://programmers.stackexchange.com/questions/71358/good-references-for-end-user-documentation-examples-and-advise) – gnat Oct 03 '13 at 18:20
  • 5
    Relevant meta discussion: [How can I reword my question in a useful manner without a clear reason why my question has been closed?](http://meta.programmers.stackexchange.com/q/6288/25936) – yannis Nov 18 '13 at 20:35

1 Answers1

3

Any strategy for providing end-user documentation is going to run headlong into the following universal law of nature:

People don't read.

I assume that, by going to the trouble of providing end-user documentation, you wish to provide additional value to the customer, in the form of improved understanding about your software product. There are a number of ways to do that. By far, the best way is to

Write the software so that it can be understood without any documentation.

Failing that, there are a number of other strategies you can employ. The traditional method of writing a manual is certainly one way, but what about:

  1. Video tutorials
  2. Quick-start guides
  3. Walkthroughs

Have you ever bought a piece of furniture from Ikea or one of those online stores and put it together using instructions from the kit? What was that experience like? If you've done one recently, you may have noticed that it consists mostly of pictures now, with very little words. Why? Because people don't read, and as they say, a picture really is worth a thousand words.

I once worked for a company that struggled with this. People would call support instead of reading the manual. How did we finally solve it? With several PowerPoint presentations that were page after page of simply walking the customer through each screen, dropdown and check box. It took about four months to do it all, but our customers loved them. They much preferred the PowerPoints over any other form of documentation that we gave them.

Video tutorials are good too, but the problem with those is they are hard to make, and they are hard to use; they have to be very short, because they're not randomly-accessible like a manual is; you kinda have to watch the whole thing. But they're great to get the lay of the software land, so to speak.

Finally, write a manual if you need a reference guide (not a how-to). That's what manuals are best at.

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
  • 1
    It really all depends on who the end user is. E.g. a sysadmin *does* read, and will probably not like videos. Devs as well. Scientists, also. But I do agree that some people won't read at all - they just want screenshots. My point is: **identify the audience first**. –  Nov 24 '13 at 23:22
  • 1
    There is some interessant points. Looking at the software market at large, it might be true that people don't read manuals, but I am in a specialised market, where people will actually use documentation. Videos as primary vehicle for information are terrible, for the reason you cite, but a hand of them can be nice. The three alternatives to documentation you propose are all good to convey what I call recipes in my other question http://programmers.stackexchange.com/q/219386/98803 (For IKEA, I think they want to avoid translations more than anything else.) – Michaël Le Barbier Nov 25 '13 at 04:04