Date: Mon, 11 Mar 1996 16:11:21 -0700 From: Sean Kelly <kelly@fsl.noaa.gov> To: jeremyc@ssimicro.com Cc: doc@freebsd.org Subject: Re: Handbook: PPP Server 1st draft Message-ID: <9603112311.AA04942@emu.fsl.noaa.gov> In-Reply-To: <199602192201.WAA00352@roc.fmbs2.gov.nt.ca> (message from Jeremy Childs on Mon, 19 Feb 1996 22:01:52 GMT)
next in thread | previous in thread | raw e-mail | index | archive | help
>>>>> "Jeremy" == Jeremy Childs <jeremyc@ssimicro.com> writes:
Jeremy> http://www.ssimicro.com/~jeremyc/ppp.html
Jeremy> Comments welcome. If you would like a copy mailed to you,
Jeremy> please let me know.
Thanks for the opportunity for review. The section looks really good!
There's a good style throughout and the instructions are easy to
follow.
Here're my inadequate comments for your truly informational document:
* 11.5 Configuring FreeBSD as a PPP Dialup Router 11.5.1 Introduction
There should always be nontrivial but perhaps introductory text
between headings. If you can't think of something, then just remove
the ``Introduction'' subhead and have 11.5.1 be the ``Prerequisites''
section.
* ... the author's personal experience ...
While there's no FreeBSD style sheet yet, I think it's perfectly
acceptable to refer to yourself in the first person. Say ``my
experience'' instead. Technical material especially should be this
way: don't think of it as being less formal but are less stilted.
It'll be easier to read and understand.
Likewise, instead of ``assumes the reader's familiarity'' just say
``assumes you're familiar with ...''
* 11.5.4 Manually Started ppp
You might want to consider putting this section (and the two that
follow) into their own section that describes the differences between
each. Online readers can see all three in perspective then, make
comparisons, and choose one by just clicking and jumping to the
appropriate heading.
Also, the HTML doesn't look like it's from the sgmlfmt program, which
means it can't be easily integrated into the FreeBSD handbook. Would
you consider making an SGML version of the document using the linuxdoc
DTD in /usr/share/sgml/FreeBSD/dtd/linuxdoc?
--
Sean Kelly
NOAA Forecast Systems Laboratory kelly@fsl.noaa.gov
Boulder Colorado USA http://www-sdd.fsl.noaa.gov/~kelly/
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?9603112311.AA04942>