ircd-hybrid/doc/guidelines.txt

ircd-hybrid documentation guidelines

1.  When a major change in the code affects users, it MUST be documented
in whats-new and all other appropriate locations.

2.  When something affects the configuration file, and it's compatibility
with previous versions, it MUST be documented in example.conf and in a
proposed new document README.NOW. This is VERY important during the beta
phase to help anyone who mans the "help desk".

3.  All documentation must properly fit in an 80 character wide terminal.
SGML and other "professional" documentation systems are good for some
projects, but hybrid is intended to be used on minimal UNIX installations
where any extra binary is a security risk. Text only docs, sized to fit
properly in an 80 character wide console, are what admins expect, and that's
what they should get.

4.  All documentation must be spell checked before a release or a beta.
'ispell' (using either the US or British dictionary) is probably the
easiest way to spell check the documentation. 'ispell -a' at the command
line will allow you to check individual words as you are editing.

5.  When a document is over approximately 5 pages long, it should be split
into sections to facilitate users reading them.

6.  All docs (except docs specifically describing code) should be written
in a way that all users of the software (not just programmers) will be able
to easily understand.

7.  Don't make documentation a chore. If it's done while coding, or shortly
after, it usually is more accurate and the documentation tasks don't get
pushed back and pile up.

8.  Don't forget to include a CVS Id.

# $Id$
Revision:	33
Committed:	Sun Oct 2 20:50:00 2005 UTC (20 years, 10 months ago) by knight
Content type:	text/plain
File size:	1617 byte(s)
Log Message:	- svn:keywords
#	User	Rev	Content
1	adx	30	ircd-hybrid documentation guidelines
2
3			1. When a major change in the code affects users, it MUST be documented
4			in whats-new and all other appropriate locations.
5
6			2. When something affects the configuration file, and it's compatibility
7			with previous versions, it MUST be documented in example.conf and in a
8			proposed new document README.NOW. This is VERY important during the beta
9			phase to help anyone who mans the "help desk".
10
11			3. All documentation must properly fit in an 80 character wide terminal.
12			SGML and other "professional" documentation systems are good for some
13			projects, but hybrid is intended to be used on minimal UNIX installations
14			where any extra binary is a security risk. Text only docs, sized to fit
15			properly in an 80 character wide console, are what admins expect, and that's
16			what they should get.
17
18			4. All documentation must be spell checked before a release or a beta.
19			'ispell' (using either the US or British dictionary) is probably the
20			easiest way to spell check the documentation. 'ispell -a' at the command
21			line will allow you to check individual words as you are editing.
22
23			5. When a document is over approximately 5 pages long, it should be split
24			into sections to facilitate users reading them.
25
26			6. All docs (except docs specifically describing code) should be written
27			in a way that all users of the software (not just programmers) will be able
28			to easily understand.
29
30			7. Don't make documentation a chore. If it's done while coding, or shortly
31			after, it usually is more accurate and the documentation tasks don't get
32			pushed back and pile up.
33
34			8. Don't forget to include a CVS Id.
35
36	knight	31	# $Id$