Date: Mon, 27 Mar 1995 14:17:38 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) To: ghelmer@alpha.dsu.edu Cc: freebsd-doc@freefall.cdrom.com Subject: Re: Dialup how-to Message-ID: <9503272117.AA09095@junco.fsl.noaa.gov> In-Reply-To: <Pine.OSF.3.91.950325202929.14158B-100000@alpha.dsu.edu> (message from Guy Helmer on Sat, 25 Mar 1995 20:34:21 -0600 (CST))
next in thread | previous in thread | raw e-mail | index | archive | help
>>>>> "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.
Of course, if this dialup document is meant to stand on its own, then
nevermind!
So, with that, here's my commentary:
In general, every heading should have text following it, instead of an
immediate subheading. It should be more than just mere metadiscourse:
``This section describes the prerequisites.'' You can make that
contain overview of what's in the section so that readers will know if
they can skip it.
2 Prerequisites
In this section, we describe what you need to set up with your
system before you can enable dialup logins. This section
tells you how to ...
2.1 FreeBSD Versions
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.
In 2.1, FreeBSD version, you might want to mention that what follows
applies to 2.x as well. Although that's implicit from the paragraph,
2.x users will feel more comfortable that the document applies if they
actually see 2.x in the text.
In 2.2, rather than make users buy a serial comms book, why not go
ahead and give brief definitions? If this is part of a FreeBSD
manual, you could have links to a glossary section.
In 2.3, second paragraph, first sentence, replace `on the end' with
`each end'. In the last sentence, replace `wire' with `wired'.
For the pathologically inept, you might also want to mention that you
don't need a serial cable for an internal modem. In the fourth
paragraph, replace `refernce' with `reference'. In the same sentence,
omit `to look up the commands.' Just end the sentence at `handy'. In
the last paragraph, last sentence, add `active' after `If the system
has many ...'
In 4, first paragraph, second sentence, omit hyphen from `multi-port'.
In the fifth and six paragraphs, you might want to mention what the
paths are for 2.x; or just forget about earlier versions and only
describe how things exist in 2.x. In the eighth paragraph, omit `like
the BB2016' which we've seen too many times already from the last
sentence.
In 6, third paragraph, last sentence, insert `get' or `receive' in
`... on a low-speed connection should <get> better interactive
response ...'
In 6.2, mention that you need to send a HUP to init to get it to
reread /etc/ttys.
In 6.3, on stty commands for FreeBSD 1.1, does that even work? Don't
serial ports go back to their default settings once they're closed
(the stty will open, set crtscts, then close the port)?
Overall, the order seems a bit off: shouldn't it be
Intro
Prerequisites
Setting up your modem (Modem settings)
Configuring your kernel (Kernel configuration)
Serial device special files (Device special files)
How logins work (Overview)
Configuring for dialup logins (Config files)
Troubleshooting
Acknowledgements
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:
To enable dialup logins on your system, do the following:
1 Hook your up modem
2 Configure your kernel
3 Make device special files
4 Set your modem's communication parameters
5 Pick locked-speed or matching-speed configuration
6 Add an entry in /etc/ttys
7 kill -1 1
8 Test it out!
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.
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.
Please feel free to ignore as much as my commentary as you feel
doesn't apply. And thanks for the writing!
--k
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?9503272117.AA09095>