Return-Path: owner-linux-activists@Niksula.hut.fi
Return-Path: <owner-linux-activists@Niksula.hut.fi>
Received: from joker.cs.hut.fi by hydra.Helsinki.FI (4.1/SMI-4.1/39)
	id AA14059; Thu, 13 May 93 07:22:25 +0300
Received: from joker.cs.hut.fi by niksula.hut.fi id <62045-10>; Thu, 13 May 1993 07:21:42 +0300
From: "Linux Activists" <linux-activists@Niksula.hut.fi>
To: "Linux-Activists" <linux-activists@Niksula.hut.fi>
Reply-To: "Linux-Activists" <linux-activists@Niksula.hut.fi>
X-Note1: Remember to put 'X-Mn-Key: DOC' to your mail body or header
Subject: Linux-Activists - DOC Channel digest. 93-4-13-0:21
X-Mn-Key: DOC
Sender: owner-linux-activists@Niksula.hut.fi
Message-Id: <93May13.072142eet_dst.62045-10@niksula.hut.fi>
Date: Thu, 13 May 1993 07:21:40 +0300
Status: RO
X-Status: 


Topics:
	 Re: Linux-Activists - DOC Channel digest. 93-4-12-4:59
	 LDP manuals outline/format


----------------------------------------------------------------------

From: jhenders@jonh.wimsey.bc.ca (John Henders)
Subject: Re: Linux-Activists - DOC Channel digest. 93-4-12-4:59
Date: Thu, 13 May 1993 00:05:44 +0300



	A modest Proposal:

	Several comments here. First, I have to agree with both sides
in several ways here. I just grabbed the docs to take a look at, and I 
agree with Vince in one way, these are great, and greatly needed out 
there right now. If I had had these a month ago, it would have saved
a dozen posts to c.o.l. Bow I understand that there is some parts that
are already out of date and inaccurate, and I would also guess that 
part of the reason there's a hesitancy to release them is that the
authors don't want to release them is that they don't want to be
swamped with hundreds of requests for clarification, so here is 
a suggestion to get around this.
	Why can't those of us who are interested in helping but don't
have a writing project offer to field the questions for the authors.
Put out the docs now after running them through detex, and don't 
put the author's e-mail address in them. Instead either put in the
address of a volunteer to take questions, or start up another channel
and have that as an address and which ever of us are interested will
subscibe there and field problems. If someone knows how to set it up
and is willing, another approch would be to grab the usenet oracle
software and use that.
	Now on the readability aspect. Have the people complaining tried 
reading these docs past the first couple of pages? I'm no TeX expert,
but I didn't have any problem at all reading the docs. It's just the setup
info at the start that looks weird, after that it's virtually all
ascii except for the occasional paragraph format command or something
to emphasize a word. In fact, I found LaTex much easier to read than
some of the TeX docs I've seen, and miles easier than trying to 
read raw nroff pages.





------------------------------

From: mdw@TC.Cornell.EDU (Matt Welsh)
Subject: LDP manuals outline/format
Date: Thu, 13 May 1993 06:11:13 +0300


I just ran into this today, and thought it might be a good idea to
model the LDP docs after this (esp. the User's Guide). Please
send me back comments. Thanks.

--
                     DOCUMENTATION MADE EASY
    (or HOW TO DOCUMENT AN APPLICATION WITHOUT REALLY TRYING)
			by Philip Hurley

Chapter 1      OVERVIEW:  This chapter contains useless 
               information which you already know because you 
               bought the product.  It details how this product 
               is better than everyone else's.

Chapter 2      INTRODUCTION:  This chapter gives you just enough 
               information to get you in trouble.  The commands 
               are explained with such brevity that it is 
               impossible to execute them successfully much less 
               understand them.

Chapter 3      UTILITIES:  This is the chapter which probably 
               should have been an introduction.  Complexity is 
               such that if you dig very deep and add what little 
               you gleaned from the first two chapters, you may 
               begin to understand how to exit the application.  
               Just enough information was scattered in the first 
               two chapters to make it impossible to skip them 
               and start with this one.

Chapter 4      EXTENDED FEATURES:  Now we're getting somewhere.  
               This is the most useful and therefore longest 
               chapter in the whole book.  It contains everything 
               you really need to know with the exception of the 
               details on how to exit/quit/abort which was in the 
               first three chapters.

                           APPENDICES
                      (or THE REAL MANUAL)

Appendix A     ERROR MESSAGES:  Deciphered form of the encrypted 
               messages you see on the screen.  This does not 
               however imply that these explainations are any 
               more understandable than the encrypted messages 
               you see on the screen.

Appendix B     TECHNICAL NOTES:  Always precede this chapter with 
               the following note:
               (NOTE:  THIS INFORMATION ONLY INTENDED FOR A 
               PROGRAMMER, I.E., HACKER.  IF YOU READ THIS 
               MATERIAL YOU WILL BE BORED TO TEARS AND MAY EVEN 
               SCREW UP THE APPLICATION.  WE WILL BE UNABLE TO 
               HELP YOU IF YOU DO THIS.)

Appendix C     SUGGESTIONS AND TIPS:  This is filled with all the 
               useful commands and hints which you already know 
               by having dug them out of chapters 1-4.  When the 
               writers of this documentation tried to use this 
               manual, they put what they learned in this 
               appendix.

Appendix D     DIFFERENCES BETWEEN THIS VERSION AND THE LAST 
               VERSION:  Boring, nitpicky changes which you 
               already know about--that's why you're using this 
               version and not the old one.

Appendix E     USING THIS APPLICATION WITH OTHER WELL KNOWN 
               APPLICATIONS:  Impossible claims of compatibility 
               with highly sophisticated and very popular 
               expensive word processors, spreadsheets, 
               databases, etc.  This chapter also contains 
               disclaimers about this application and that 
               application running on your particular computer.

Appendix F     INSTALLATION:  What you should have read from the 
               very beginning.

Appendix G     GLOSSARY:  The reason we bought an expensive, 
               well-known third party product for word processing 
               which generates this nifty, keen glossary.

--
mdw




------------------------------

End of DOC Digest
*****************
-------
