Writing Documentation

 Back in 2006 Andy Orem did an interesting research project.
The basic conclusion is below.

When someone comes to a mailing list, there are three possible causes—three types of information failure:

1. The information has not been written anywhere. This is a common problem, despite the vast amount of written computer documentation. There are many subtleties in complex software that have gone unexplained. Information may also be missing for bugs or quirks in newly released software.
2. The information has been written, but it is prohibitively hard to find. This happens because web searches are not perfect, and few projects provide well-organized collections of pointers to the relevant information stored in idiosyncratic places.
3. The information has been written and can be found, but the user does not know how to find it. This is part of the larger education problem I have been discussing.

Do-It-Yourself Documentation?

Research Into the Effectiveness of Mailing Lists

Andy Oram

August 19, 2006

(Revised September 22, 2006)

http://praxagora.com/andyo/professional/mailing_list/mailing_list.html


I am currently writing An e-Sword Users Manual. Much as I would like to think that  The e-Sword Utility Program FAQ would merely put the information into either the prohibitively hard to find category, or the user does not know how to find it category, into the easy to find category, I have become increasingly convinced that it is all in the has not been written anywhere category.

It doesn't matter if it is something as simple as opening a topical file in e-Sword, or as complicated as "I want to study the inflections of the Hebrew middle weak verb, and I want to see what the range of possible variations is for each of the conjugations (perfect, imperative, etc.) person, number, gender, and stem. This means I need to find all the middle weak verbs, find all their occurrences, and organize them in such a way that the variation of their inflections are immediately apparent. The goal of the data organization would be to allow me to write an article about the variations of the Hebrew middle weak verb."

The written documentation is not present. There are videos on YouTube, e-Sword.net, and other locations. But they don't substitute for scanning a document, or a table of contents, looking for how to perform the two things described in the previous paragraph.

It is getting increasingly more difficult for me to write documentation, because my starting point is very different from that of most users. This can be seen in the Bible Software reviews I've written, where my first three test cases are:

• Give the parsing of a word and its meaning from a standard source;
• Show all the occurrences of a word in the NT and LXX and show the Hebrew word which corresponds with the Greek in the LXX (if there is a correspondence);
• Find all the occurrences of oi de in Matthew’s gospel followed by a finite verb within the clause;

Those three examples are from the SBL Bible Software Shootout.  (You can use e-Sword for all five challenges. How to do so is a self-standing volume  of An e-Sword Users Manual.)


It is hard for me to think like a person who does not know how to use a computer.  Fortunately, somebody volunteered to review the documentation I'm writing, and tell me when they don't understand what I've written.  Even better for me, they think like a person that does not know how to use a computer.  Their red lining, and telling me to rewrite the section, has helped write other sections, so that they don't need to be red lined.

That process is more time consuming that I originally anticipated.  But I think the results will be worth it.  And you can blame it all on Andy's research, identifying the major causes for people emailing mailing lists.