|
1 <html> |
|
2 <head> |
|
3 <title> DTN2 Manual: Style Guide </title> |
|
4 <link rel="stylesheet" type="text/css" href="manual.css" /> |
|
5 </head> |
|
6 <body> |
|
7 <h1>Style Guide |
|
8 </h1> |
|
9 |
|
10 <h2> Writing </h2> |
|
11 |
|
12 <p> |
|
13 Write the kind of documentation that you would like to read. |
|
14 Our role models are old Unix man pages and the MySQL online HTML |
|
15 pages (with user comments!). |
|
16 Our anti-role-models are Windows help pages: "To start a new file, |
|
17 choose File -> New". |
|
18 |
|
19 <p> |
|
20 Know your audience. Be chatty and explain concepts in a tutorial |
|
21 page. In a reference page be above all precise, then concise, and |
|
22 finally if possible be interesting to read (but this is a distant third). |
|
23 For every setting where it makes sense (and it almost always does) |
|
24 be crystal clear about what the default is. Offer guidance on |
|
25 what the best practices are and why. |
|
26 |
|
27 <p> |
|
28 Be honest about limits, shortcomings, misbehavior and the like. |
|
29 When it makes sense, document internal things (include a disclaimer |
|
30 that this is something internal, and if you count on it not changing |
|
31 you'll probably be surprised.) |
|
32 We have no secrets to hide, we have no marketing department to |
|
33 keep happy. |
|
34 |
|
35 <p> |
|
36 Read more than you write. While warming up to bang out a new |
|
37 section of the manual, proofread a page and look for ways the code |
|
38 has changed from when the page was written. |
|
39 You should almost always find yourself reading code in order |
|
40 to write the docs about it. For some of this code, writing the |
|
41 documentation on it is the closest to careful QA it will ever get. |
|
42 Don't pass up this chance to kill a few bugs. |
|
43 |
|
44 <h2> HTML Stuff </h2> |
|
45 |
|
46 <ul> |
|
47 <li> Use the template.html file to start a new file. |
|
48 |
|
49 <li> If you refer to a file that does not exist yet with an href, |
|
50 make it exist as a stub using the content in the template.html file. |
|
51 This will hopefully encourage people who stumble across it to help us. |
|
52 |
|
53 <li> Try for high quality HTML, but don't kill yourself to be |
|
54 XHTML 9.x (or whatever the newest annoying thing is from W3C). |
|
55 |
|
56 <li> Use CSS sparingly to improve readability and simplify the HTML |
|
57 code. I'd be surprised/unhappy if we ended up with more then 20 |
|
58 styles. |
|
59 |
|
60 <li> Our targeted web browsers are w3m and Firefox. Realistically, |
|
61 every other browser is between these two in capabilities. (w3m is like |
|
62 Lynx, but can do tables.) |
|
63 |
|
64 <li> Usage of <tt>, <b>, and <i> is not very |
|
65 well standardized yet. tt is usually for verbatim output or input. |
|
66 i is usually for a variable representing user input. |
|
67 |
|
68 <li> There's no excuse for these pages to be too big to download |
|
69 at 9600 baud from the middle of Africa. Trim fat if doing so does not |
|
70 hurt the final product. |
|
71 |
|
72 </ul> |
|
73 |
|
74 <h2> Copyright </h2> |
|
75 |
|
76 <p> |
|
77 Your contributions to the manual are on the same terms as the rest |
|
78 of the project. Read the license and decide if you can accept it |
|
79 before submitting documentation. |
|
80 |
|
81 </body> |
|
82 </html> |
|
83 |