Date: Fri, 6 Nov 1998 20:15:47 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: doc@FreeBSD.ORG Subject: Doc. Project. Primer, please read and comment Message-ID: <19981106201547.11656@nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
OK, you know how it is.
This was going to be a small, simple tutorial on how to use DocBook with
the Documentation Project, and how the Handbook is built.
It's grown a bit :-)
It's now what I'm calling "The FreeBSD Documentation Project Primer for
Contributors". The idea is that someone comes along to the -doc mailing
list and says "Hi, I'd like to contribute, what can I do?".
We say "Please go and read *this* (or at least, skip those bits you're
comfortable with, read those bits that are new to you). This'll bring you
up to speed on what the Project is, how it works, what we use, enough
SGML to get you started, and information on how the Handbook, FAQ, and
web site are put together. Then go to the Doc. Proj. projects page on
the web site and pick something you like the look of. OK?"
As ever, I need criticisms and contributors.
- I think the SGML Primer is pretty much complete. Could people please
read through it and let me know if it's confusing or if the
information should be reordered or augmented.
- The Tools section needs fleshing out.
- The SGML Markup section needs fleshing out. HTML is completely empty;
I can fill that in later myself, or someone else can do it (please!)
DocBook is a little disorganised, since I haven't done anything
with it since I changed the direction of this tutorial. I'll sort
that out soon.
LinuxDoc is empty, and will stay that way unless someone writes
something to go in there. I know next to nothing about the DTD.
- The FAQ should cover how the FAQ is made, what files make it up, and
so on. If the FAQmeister could step up to the plate on this one. . .
(or anyone else for that matter).
- The Handbook section -- I've got most of the text for this,
unfortunately it's mixed in with the DocBook section. I'll split it out
later.
- The Website. As with the FAQ. At least here I already know how the
website is put together, and could write this myself if no one wants
to.
- Writing style is my own list of do's and don'ts. Please feel free to
suggest more.
- Ditto to "Using sgml-mode with Emacs".
- See also will be pointers to other references. It's pretty empty at
the moment.
It's at <URL:http://www.freebsd.org/~nik/primer/index.html>; (or will be
within a few minutes of this message hitting the lists).
N
--
C.R.F. Consulting -- we're run to make me richer. . .
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981106201547.11656>