Good documentation

LMMS

LMMS original documentation:

• Little content
• what was there could be guessed anyway

Ask developers to fix bugs, develop features, write documentations.

Developers:

• Users asking stupid questions
• Fixing bugs more important
• One developer

I decided to write the documentation

• I was the one asking stupid questions
• Documentation helps other people learn
• Learn more about the program
• If I contribute, maybe they will solve some of my problems for me.

Users love good documentation.

Developers love good documentation

• Users can help other users
• Users can write there own documentation
• Users can become developers

Starting documentation

I wanted everything I didn’t already know.

• What do all the controls do? What do all the filters do?

What do other people want from the documentation.

• What they don’t already know.

Different types of documentation

• Novices: people who don’t know this particular program.
  • tutorials
  • How? How do I use the program?
• Intermediate: why am I following this procedure? Is there a better way.
  • subject guides
  • often not covered sufficiently
  • look for related tools
  • look for related goals
  • e.g. which tool do you use in Gimp for blurring part of an image? Why choose one tool over another?
  • Why? Why do I use this button over this other button?
• Advanced: Want to know the details of everything
  • detailed reference manuals that specify every detail of the program.
  • reference
  • What? What does this button do?

Writing documentation

Documentation is just another project.

How do you normally write code?

• Top down view
• Bottom up
• Both at the same time
  • Plan overall structure. Divide into chapters and sections. Write.

1. Introduction
2. Tutorials
3. Subject Guides
4. Reference
5. Appendices

Cooling off period from doing significant amount of development to write the documention. You are too familiar with it and can’t see it from an outsiders point of view.

Review process is important. Make sure you understand what you wrote a month later.

Get raw information from developer, and have somebody else document it. Developer may have to explain it. In some cases developer may not be able to explain own code and rewrite it. Having to explain it forces developer to think about issues from point of view of users and see issues they missed before. Sometimes code coverges to documentation. Sometimes documentation converges to code. Sometimes code and documentation diverge.

Shortage of developers means developers reluctant to make anything other then minor changes.

Give yourself a pat on the back, e.g. chocolate, drink, go out for walk, when you have succeeded in writing a section. Otherwise it is not as rewarding as writing code. That way you feel better about coming back to the code.

Be consistent

• terms - glossary
• layout and formatting
• don’t be afraid to rewrite

Tool

Only use one tool. Use a wiki.

• Cross-referencing.
• Revision view and control.
• Many editors.
• Indexable by google.

Ship product in other documentation formats.

Integrating documentation into application. Being able to link to specific wiki page is good.

Floss Manuals - one button approach to turn twiki content into PDF.

Requirements:

• Link with text that is different to link name.
• Being able to serve static objects.
• Simple URLs. Google likes them better. No get arguements.
• footnotes.

Style

• clean
• concise
  • say no more then you need
• precise
  • unambiguous and consistent
  • doesn’t always mean adding more words
• literate
  • spelling, punctuation, grammar
  • not as precise as compiler requirements
• correct
  • accurately reflect state of program
  • up to date

Having old documentation is useful, because some users will be using old version. Need to keep old versions out of the way, as users might find them with google search results.

Facts

Users and developers love good documentation.

Use a wiki

Style matters

Time

“But I don’t have time!”

Yes you do have time. Write good documentation.