trunk/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 reference.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:	1823
Committed:	Sun Apr 14 18:24:38 2013 UTC (13 years, 3 months ago) by michael
Content type:	text/plain
File size:	1619 byte(s)
Log Message:	- Renamed example.conf to reference.conf - Due to upcoming feature implementation, resv{} blocks are no longer stackable
#	Content
1	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 reference.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	# $Id$