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 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 |
# $Id$ |