Date: Tue, 28 Mar 1995 14:01:50 -0600 (CST) From: Guy Helmer <ghelmer@alpha.dsu.edu> To: Sean Kelly <kelly@fsl.noaa.gov> Cc: freebsd-doc@freefall.cdrom.com Subject: Doc project guidance, was Re: Dialup how-to Message-ID: <Pine.OSF.3.91.950328134629.9503D-100000@alpha.dsu.edu> In-Reply-To: <9503272117.AA09095@junco.fsl.noaa.gov>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 27 Mar 1995, Sean Kelly wrote: > >>>>> "Guy" == Guy Helmer <ghelmer@alpha.dsu.edu> writes: > > Guy> Anyway, a rough start can be viewed at > Guy> "http://www.dsu.edu/~ghelmer/FreeBSD/dialup.html". Please > Guy> check it over and mail me comments or suggestions > Guy> (good/bad/toss it!). > > It looks great! The document has a good conversational style that > facilitates understanding. And it's really quite thorough. > > I'm not sure how deep an edit/commentary you wanted, but before I > could take a look, I ran into a few questions of my own for the doc > group at large: is there a FreeBSD doc style sheet? If not, there > needs to be lest we all start writing in wildly different styles. I think we've been writing in our own styles -- I don't know that a common style has been considered. It was hard enough deciding on a common source format (linuxdoc DTD) :-) BTW, I appreciated the depth of your commentary. It brings up a number of issues on which I would like to have some guidance. > Of course, if this dialup document is meant to stand on its own, then > nevermind! No, I hope that if it is acceptable, it would be included in the FreeBSD Doc How-To pages. > So, with that, here's my commentary: > [... I've edited out the parts specific to improvements in my dialup > doc ...] > > Also, if this is to be included in a large multiauthor FreeBSD manual, > you should replace the first person with the third while still > maintaining the conversational style. Done, and this is probably important for all our docs. > ahead and give brief definitions? If this is part of a FreeBSD > manual, you could have links to a glossary section. Hmm - shall we develop a "Glossary" page for the FreeBSD How-To docs? > You might want to include a step-by-step overview (using an ordered > list) at the beginning the document so that more experienced users can > quickly edit the needed files and get going. Each step can link to > what you've written now so that beginners can get the needed details: Perhaps this is another good idea for all how-to docs. > Also, make commands that the user types (like /sbin/dmesg|grep sio) > stand out on a line by themselves. This makes it easier to paste into > an xterm window. Ditto. > Finally, if this is to be part of a larger user manual, factor out all > the stuff on kernel config, device special files, cables, FreeBSD > version, terminology, etc. and focus on what the user came here to > read: enabling dialup logins. The rest of that stuff should be > available as links, but not part of the document that one would read > straight through. This modularity helps people who want to link to > your document as well. For example, if I'm writing a section on > setting up a PPP server, I can plant a link to yours when I need to > tell my reader that s/he needs to first enable dial up logins. I can > reuse the troubleshooting and kernel config sections as well through > links. OK, so perhaps we need: 1) Kernel How-To: config, build, and install 2) Device Special Files Reference: MAKEDEV; file permissions 3) Glossary 4) Index There was quite a bit of overlap between my SLIP Server how-to and this dialup how-to in the kernel area. I'm inclined to leave the dialup how-to as is until the the kernel how-to and device special files reference are ready. If anyone has comments or would like to help/take on some of these things, please let me know. Otherwise, I'll start tackling them myself as time permits. > Please feel free to ignore as much as my commentary as you feel > doesn't apply. And thanks for the writing! Thanks for your comments! > --k Guy Helmer, Dakota State University Computing Services - ghelmer@alpha.dsu.edu
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.OSF.3.91.950328134629.9503D-100000>