Web-Only Documentation: A Stupid Idea

Today while trying to figure out how to use two graphics packages, I discovered that people without internet connections apparently don't deserve documentation. I am still ignorant of how to rotate shapes in both Inkscape and Xara LX (two programs that will never ever challenge any real vector graphics software) assuming it's even possible, because the documentation is provided as a web link.

This seems like a strange thing to say on a webpage, but I am not connected to the internet as I write this! This article is being written in a period of downtime in which I am editing web content on a local copy on my laptop which will replace the current contents of my site. And this, of course, is the problem. It makes every bit of sense to provide a link to the latest documentation on the web inside the documentation. But not including documentation with the program is a move for idiots. It says that you do not care enough about the user experience to include any documentation. And it also says to the world that the developers don't know how the program works - they're just out there writing code.

Some programs don't particularly need much documentation; that's great. They have user interfaces that are laid out logically and which don't really require any advanced information to fathom. These programs don't really need any documentation, although it is always a mistake not to have any. Regardless, documentation should always come with the program. It's not unreasonable for the documentation to be a separate package, especially in the case of Unix systems with integrated package management. But it simply makes no sense for there not to be any local documentation.

The truly sad part is that if you are using any halfway decent system for your online documentation, you can export it to another format or even a subset of its own HTML for use offline. This does not happen for one or both of two reasons:

  • The people packaging the program are doing the work for their own glory, and don't actually care if you can use the software.
  • The people maintaining the online documentation are idiots who can't figure out how export the documentation.

Please, fight against software stupidity. Write and include documentation with your program. If you don't know what the program is supposed to do in a given instance, how do you even know it's working correctly?

Add new comment

Default

  • Use [fn]...[/fn] (or <fn>...</fn>) to insert automatically numbered footnotes.
  • You may link to images on this site using a special syntax
  • Web page addresses and e-mail addresses turn into links automatically.
  • To post pieces of code, surround them with <code>...</code> tags. For PHP code, you can use <?php ... ?>, which will also colour it based on syntax.
  • Internal paths in single or double quotes, written as "internal:node/99", for example, are replaced with the appropriate absolute URL or path. Paths to files in single or double quotes, written as "files:somefile.ext", for example, are replaced with the appropriate URL that can be used to download the file.
  • Filtered words will be replaced with the filtered version of the word.
  • Lines and paragraphs break automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <blockquote> <q>

Issue

  • Lines and paragraphs break automatically.
  • To post pieces of code, surround them with <code>...</code> tags. For PHP code, you can use <?php ... ?>, which will also colour it based on syntax.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>

Drinking Game

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <img> <p> <br> <pre> <h2> <h3> <h4>
  • Images may be embedded like: [image:node_id align=alignment hspace=n vspace=n border=n size=label width=n height=n nolink=(0|1) class=name style=style-data node=id] Leave off any attributes you don't want.
  • [img_assist|...] tags will be displayed, maybe. Please don't make more of them.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
Refresh Type the characters you see in this picture. Type the characters you see in the picture; if you can't read them, submit the form and a new image will be generated. Not case sensitive.  Switch to audio verification.