Date: Thu, 23 May 1996 11:33:21 -0600 From: Sean Kelly <kelly@fsl.noaa.gov> To: jrclark@felix.iupui.edu Cc: doc@freebsd.org Subject: Re: FAQ Contribution Message-ID: <9605231733.AA26497@fslg8.fsl.noaa.gov> In-Reply-To: <2.2.32.19960523130853.006972e4@felix.iupui.edu> (message from John Clark on Thu, 23 May 1996 09:08:53 -0400)
next in thread | previous in thread | raw e-mail | index | archive | help
>>>>> "John" == John Clark <jrclark@felix.iupui.edu> writes:
John> Documentation Maintainers:
Yes?
John> Recently I switched from Linux to FreeBSD.
Congratulations, and thanks.
John> Doing this allowed me to see some serious holes in your
John> documentation. Probably among the worst is the total lack
John> of coherent directions for using the "ports" collection.
I'm afraid I have to be critical as well here. With utmost resepect
to Misters Palmer and Hubbard, the ports section could certainly use
some work to make it more tutorial and less meandering. It reads like
a FAQ and not at all like the tone I think we need in a handbook.
Perhaps someone could rewrite that section into a more tutorial-like
form?
John> You have a great deal of the documentation in place for this
John> topic in the handbook, however, key details are missing.
John> Most prominently, there is NO mention, anywhere, that one
John> has to type "get portname.tar.gz" to fetch the port
John> subdirectory from cdrom.com.
To be thorough though, that step isn't actually necessary in all
cases. For example, if you've got an Internet connection and
installed the ports collection from your CD-ROM or made a symbolic
link tree to the CD-ROM, a simple `make' will automatically fetch the
port sources for the port in question.
John> One sentence in the handbook could rectify this.
True.
John> There are other problems as far as conveying the concept of
John> how the port is used and its relationship to the generic
John> internet distribution of the "port" in question.
I don't understand. Huh?
John> Anyway, I have written a FAQ to be added on this subject.
Great! I'd be willing to convert your FAQ into the SGML format needed
for the FreeBSD documentation project.
However, if you'd like to to do this yourself, it'd be an excellent
opportunity to learn the DTD that we're using for the FAQ and the
handbook ... which would be useful information for future
contributions ... hint, hint :-)
I've skimmed through your FAQ and will have complete comments
available by Saturday. Thanks for the contribution!
--
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?9605231733.AA26497>