http://www.politiker-stopp.de/gfx/politiker-stopp-print.png

Benjamin Schieder

[TECHSUCKS] BAD DOCUMENTATION BETTER THAN NO DOCUMENTATION?

2006 July 23 | 0 comments

The first question:

Is bad documentation better than no documentation?


This really depends on your point of view. As a user, you not only want good documentation, you want perfect documentation. In Germany, you can even bring back a product for a refund if the documentation is faulty.
As a developer, you might think that there is documentation, no matter how bad it is, and tell your users to stop complaining. Maybe that's okay for you, but it certainly isn't for the users.
Let's have a look at the man page of mplayer. First observation: It's BIG. It's so big you might think it has an inferiority complex. Here's a particularly nasty excerpt:
-font (OSD only)
Search for the OSD/SUB fonts in an alternative directory (default for normal
fonts: ~/.mplayer/font/font.desc, default for FreeType fonts: ~/.mplayer/sub-
font.ttf).
NOTE: With FreeType, this option determines the path to the text font file.
With fontconfig, this option determines the fontconfig font name.

EXAMPLE:
-font ~/.mplayer/arial-14/font.desc
-font ~/.mplayer/arialuni.ttf
-font 'Bitstream Vera Sans'

-fontconfig (fontconfig only)
Enables the usage of fontconfig managed fonts.


There are two problems here I would like to point out:
  1. inconsistent information
    In the very first line it says '-font (OSD only)'.
    And in the next line: 'Search for the OSD/SUB fonts in an alternative directory'. Emphasis mine. So first it says 'OSD only' and then it says 'OSD/SUB'. Which one is correct?
  2. incorrect/misleading/misrepresented information
    It then goes on to show that the '-font' parameter may take one of three different types of parameters depending on how mplayer was compiled. This is already bad enough in itself, but it then clearly fails to state how one can figure out how it was compiled.


The second item brings me to the next question:
How difficult is it to get the documentation right?


I don't think it can be that difficult. For the example above you can - for example - create a batch of text files you later catenate together to the man-page. Subsequent parts of the man-page get catenated together depending on configuration (config.h for autotools, for example). Or create it from a --help parameter of the program with a bunch of #ifdef in the code (like nethack does on the in-game version information).

So far I still haven't managed to change the font and/or size of the mplayer subtitles. If anyone knows if this is even possible and the relevant part of the man-page isn't just bait, please let me know.


EOF

Category: blog

Tags: TechSucks documentation developer mplayer problems example


Post a comment

All comments are held for moderation; basic HTML formatting is accepted.

Name: (required)
E-mail: (required, not published)
Website: (optional)
Comment: