[Psi-devel] Documenting Psi

[Trejkaz Xaoza]

On Sun, 11 Jul 2004 03:18, Ben Branders wrote:
> The installation on Windows, Linux and Mac is already on the todolist.
> Maybe the some of the options can be documented too...

Are installation instructions really required in this day and age?  Windows 
users double click an MSI file or a .exe wrapping an MSI file, and the 
program is installed.  Macintosh users can probably just do two mouse drags 
and it would work.  And Linux and BSD users have a different install process 
depending on the distro (many of those won't even need to visit the web site 
to install the program.)

In any case, if the installation instructions must be done, we would want the 
manual in two parts.

The first part would be the Complete Idiot's Guide, which contains everything 
they need to know to get the application installed and running, and so that 
they know where to get to the help feature.  Approximately zero people would 
actually read this, and anyone who reads it would either understand it and 
realise they didn't need to, or not understand it anyway (and botch the 
install.)  A true-to-form Complete Idiot will think they don't need to read 
the manual, will botch the install, and will be on the forums 15 seconds 
later saying how MSN installed easier (i.e., it was installed already.)

The second part would be the actual manual, and (DocBook makes this really 
easy) you would have an online version, an installed version (which could 
also become Psi's context sensitive help!) and a printable version, for 
loonies.  Actually you could probably decide not to produce a printable 
version as a matter of environmental policy. ;-)

The biggest problem with manuals from what I've found is the screenshots.  
Every feature which changes means another screen which is wrong in the 
manual.  Do we have a way around this annoyance yet?  Screenshots cost me 
about 16 hours solid work in my current job, for a minor revision of our 
product. :-/

TX

-- 
'Every sufficiently advanced technology is indistinguishable from magic' - 
Arthur C Clarke
'Every sufficiently advanced magic is indistinguishable from technology' - Tom 
Graves

             Email: Trejkaz Xaoza <trejkaz at xaoza.net>
          Web site: http://xaoza.net/trejkaz/
         Jabber ID: trejkaz at jabber.xaoza.net
   GPG Fingerprint: 9EEB 97D7 8F7B 7977 F39F  A62C B8C7 BC8B 037E EA73