Date: Fri, 6 Jan 1995 01:52:25 -0800 From: "Jordan K. Hubbard" <jkh> To: hackers Cc: antwerp Subject: Desperately Seeking Doc hackers! Message-ID: <199501060952.BAA10713@freefall.cdrom.com>
next in thread | raw e-mail | index | archive | help
OK, folks.. It's time to start the FreeBSD Documentation Project - it's long overdue! We need people to: o Write mini-FAQs o Write meta-FAQs (overviews, indices, etc). o Write tutorial guides (longer than mini-FAQs, not in "FAQ" format). o Help bring over the Linux SGML doc environment. o Oversee the doc project and set overall direction (editor). o Work with the Webmasters (www@freebsd.org) in pasting it all together into a homogenous whole. We need to deal with HTML, cleartext and Postscript output in the short term. In the long term, we should also support info. o Clean up and hypertextify the man pages (apparently, there's already a tool to do this automagically). o Look at all the old stuff in /usr/share/doc and refile, delete or fix. I figured that the home of the DOC project should be /usr/src/share/doc/freebsd. The old stuff can stay alongside it or get shuffled into /usr/src/share/doc/old where it can molder in peace until we've either outdated it or picked at it for all the value that could be derived. The existing stuff will stay in /usr/src/share/FAQ, which should be eventually deprecated. The build process will probably involve taking /usr/src/share/doc/freebsd/SGML/... and building one or more documents in /usr/share/doc/freebsd/ASCII/ or /usr/share/doc/freebsd/Postscript/ for distribution with the docdist. Ideally, I'd like to see this taken over entirely by one `docmaster', who would join the core team (if not already a member) and hold overall responsibility for FreeBSD documentation. If all else fails, I'll take it on, but I'd rather not. I really don't have the time available for any more intensive writing right now! :-( I'd expect things to proceed along the following lines: 1. Appoint docmaster. 2. Solidify plans concerning markup language to be used (I'm presuming SGML at this point) and which initial output formats the FDP will be expected to provide. 3. Docmaster assembles team. 4. Team sends report to hackers detailing what they have in mind. 5. Rest of community kibbitzes for awhile, eventually quiets down, team considers feedback for short time then work begins in earnest. 6. Poul-Henning Kamp & I work closely with Docmaster & team on scheduling docs to go into FreeBSD 2.1, which docs are provided before, during and after the installation process, etc. 7. Simultaneously, the Webmasters start pasting in some of the initial HTML output and feeding back to the Docs team on how it all looks. I'd also like to take this chance to mention that the Web pages have been going amazingly well, and anyone who hasn't looked at http://www.freebsd.org yet is strongly encouraged to do so! Kudos to John Fieber and James L Robinson for a very impressive job so far. It's been their success more than anything else that's been motivating me to take a long, hard look at our docs, and I'm not very happy with what I'm seeing. We REALLY need to change this if we are to have any hope of really reaching a large number of people! The Linux Doc Project has generated an amazingly large amount of very good documentation, and we've basically done squat. Shame on us! I take this lack of good doc very seriously, as most of you who know me already know, and I think it's time that we all took it seriously enough to form a complete team who's only thought is DOC! Thoughts? Jordan
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199501060952.BAA10713>