Re: Structure for GUI & Command Line Input Doc

[Sandy Harris <pashley -at- storm -dot- ca>]

CB Casper wrote:
> 
> I have inherited a user manual for a product that
> includes both a GUI and a Command Line Interface
> to configure the software/hardware on Unix.
> 
> Currently there are separate chapters for GUI &
> CLI, and am questioning the wisdom of this practice.
> 
> Recognizing that some commands are not available
> through the GUI, yet a lot of the information is
> duplicated in both chapters.

I'm an old Unix user. For me, question one is whether
the man pages are done. If not, I'd say do them first.

Traditionally, everything on a Unix system -- user
commands, file formats, admin commands, programmers'
libraries, ... -- must have a man page. These are
accessible on-line, printable by the user (also often
provided in book format by the vendor) and have a
cross-reference system.

> I am contemplating combining these two chapters
> to emphasize the commands and actions rather than
> the means to accomplish the task. I want to focus
> on what the user is trying to do, rather than how
> they accomplish it.

I'd put the reference material as man pages, then
do tutorial and task-oriented stuff with lots of
cross-references to them.

The man page standard for cross-references is quite
simple. (This is a mid-70s design, after all.) You
just put a number in brackets after a name, so for
example, chmod(1) refers to the user command that
changes the mode of a file (manual section 1) and
chmod(2) to the system call a programmer can use
to do that (section 2).
 
> It makes sense to me anyway. If I want to accomplish
> a certain task, I need to know WHAT command & options
> to use. Secondarily, I then need to know HOW to do it.
> 
> Any real world examples or experience would be
> appreciated, along with thoughts on this.

I documented a Linux application called FreeS/WAN.
Docs are online at:
http://www.freeswan.org/doc.html

The developers wrote man pages. Project policy -- one
I'd advocate for any Unix project -- was that everything 
had to have a man page.

Fortunately, the developers were all quite literate,
so I didn't touch the man pages, other than making
the odd comment. I just converted them to HTML so
I could link to them. 
http://www.freeswan.org/freeswan_trees/freeswan-1.95/doc/manpages.html

My links are things like "ipsec.conf(5)" inside
HTML tags. The user then gets a choice. Follow
the link to the HTML version, or use the command
man 5 ipsec.conf
to read it from the command line, or go look in
section 5 of the printed manuals.

There are several free man2html utilities around.
For scripts that call one, and automatically turn
man page cross-references into HTML links, see: 
http://www.freeswan.org/freeswan_trees/freeswan-1.95/doc/Makefile

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.