Re: Bad Documentation and Linux

[Sandy Harris <sandyinchina -at- gmail -dot- com>]

On 12/5/09, neilson -at- windstream -dot- net <neilson -at- windstream -dot- net> wrote:

>  For Linux (or any Unix) if you want to do command-line stuff, you have
> to wade through hairy documentation that tells you about hairy options
> you'd rather ignore.

Saw a T-shirt once: "Real cats don't have options."
A quick check shows Gnu cat has eight.

> Personally, I like Unix command lines and am willing to read
> man pages.

Me too.

I complain rather vehemently whenever someone tries to foist some
product on me without documentation that meets what I consider
the minimum standard, set by Unix in the 70s -- complete, readable
online, printable, and with extensive cross-references.

That said, there are problems.

First off, while a good set of man pages may be a complete
reference, they are not complete documentation; even 70s
versions of Unix had Volume II of the manual, tutorial
materials. Linux has HowTo documents, FAQs, wikis, ...

Secondly, there are format difficulties. Gnu docs are not primarily
in man page format, but Texinfo. This has advantages, but when
you mix programs from multiple sources, you get a doc problem.
It is by no means insoluble -- the solution I like is converting both
man and info files to HTML for delivery, but there are several
other possibilities -- but it is a poblem.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you looking for one documentation tool that does it all? Author, 
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:
http://www.doctohelp.com/ 

Help & Manual 5: The all-in-one help authoring tool. True single- sourcing -- 
generate 8 different formats and as many different versions as you need 
from just one project. Fast and intuitive.  http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat