From owner-freebsd-doc Mon Mar 11 15:11:26 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id PAA27888 for doc-outgoing; Mon, 11 Mar 1996 15:11:26 -0800 (PST) Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id PAA27882 for ; Mon, 11 Mar 1996 15:11:24 -0800 (PST) Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA10701; Mon, 11 Mar 96 23:11:22 GMT Received: by emu.fsl.noaa.gov (1.38.193.4/SMI-4.1 (1.38.193.4)) id AA04942; Mon, 11 Mar 1996 16:11:21 -0700 Date: Mon, 11 Mar 1996 16:11:21 -0700 Message-Id: <9603112311.AA04942@emu.fsl.noaa.gov> From: Sean Kelly To: jeremyc@ssimicro.com Cc: doc@freebsd.org In-Reply-To: <199602192201.WAA00352@roc.fmbs2.gov.nt.ca> (message from Jeremy Childs on Mon, 19 Feb 1996 22:01:52 GMT) Subject: Re: Handbook: PPP Server 1st draft Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk >>>>> "Jeremy" == Jeremy Childs 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/