1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Basics of Documentation Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"><link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation"><link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation"><link rel="previous" href="indexs11.html" title="Referring to Other GNOME Documentation (coming in 2 GNOME-2.0)"><link rel="next" href="indexs13.html" title="Teamwork"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basics of Documentation Style</th></tr><tr><td width="20%" align="left"><a href="indexs11.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a href="indexs13.html">Next</a></td></tr></table><hr></div><div class="sect1"><a name="basics"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="basics"></a>Basics of Documentation Style</h2></div></div><p> 3 Most people have never enjoyed reading a software manual, and 4 they probably never will. Many times, they'll read the 5 documentation only when they run into problems, and they'll be 6 frustrated and upset before they even read a word. On the 7 other hand, some readers will read the manual all the way 8 through, or at least look at the introduction before they 9 start. Your document might serve as a reference for an expert 10 or a guide to a beginner, and it must have enough depth to 11 satisfy the first without overwhelming the second. Ideally, it 12 will serve beginners as they <i>become</i> 13 experts. Remember, your goal is to produce <i>complete, 14 intuitive and clear</i> documentation. 15 </p><p> 16 In order to write useful documentation, you'll have to know who 17 your audience is likely to be. Then, you can look for the 18 problems they're likely to run into, and solve them. It will 19 also help if you focus on the tasks users will perform, and 20 group features accordingly, rather than simply describing 21 features at random. 22 </p><div class="sect2"><a name="styleplanning"></a><div class="titlepage"><div><h3 class="title"><a name="styleplanning"></a>Planning</h3></div></div><p> 23 Begin documenting by learning how to use the application and 24 reading over any existing documentation. Pay attention to 25 places where your document will differ from the template. It 26 may help to develop a document skeleton: a valid XML or SGML 27 document that has little or no content. For very large 28 applications, you will need to make significant departures 29 from the templates, since you'll be using the 30 <tt><book></tt> tag instead of 31 <tt><chapter></tt> or 32 <tt><article></tt>. 33 </p></div><div class="sect2"><a name="balance"></a><div class="titlepage"><div><h3 class="title"><a name="balance"></a>Achieving a Balanced Style</h3></div></div><p> 34 Just as you need to juggle expert and novice readers, 35 you'll have to juggle a number of other extremes as you write: 36 <div class="itemizedlist"><ul><li><p><a name="id2941166"></a> 37 Documents should be complete, yet concise. You should 38 describe every feature, but you'll have decide how much 39 detail is really necessary. It's not, for example, 40 necessary to describe every button and form field in a 41 dialog box, but you should make sure that your readers 42 know how to bring up the dialog and what it does. If 43 you spend fewer words on the obvious, you can spend more 44 time clarifying the ambiguous labels and explaining 45 items that are more complex. 46 </p></li><li><p><a name="id2941193"></a> 47 Be engaging and friendly, yet professional. Games 48 documents may be less formal than productivity 49 application documents (people don't 50 <i>use</i> games, they 51 <i>play</i> them), but all of them should 52 maintain a standard of style which holds the reader's 53 interest without resorting to jokes and untranslatable 54 allusions or puns. 55 </p></li><li><p><a name="id2941232"></a> 56 Examples, tips, notes, and screenshots are useful to 57 break up long stretches of text, but too many can get in 58 the way, and make your documents too choppy to read. 59 It's good to provide a screenshot of any dialog windows 60 a user might run into, but if a dialog box has several 61 tabs, it's not usually necessary to have one for each. 62 </p></li><li><p><a name="id2941255"></a> 63 The GDP strives to have all of its documentation conform 64 to certain standards of style and content, but every 65 document (and every writer) is different. You will need 66 to use your judgement, and write documents to fit with 67 the rest of the project, without compromising the 68 individual needs of your subject, or your own 69 individuality as a writer. 70 </p></li></ul></div> 71 </p></div><div class="sect2"><a name="stylestructure"></a><div class="titlepage"><div><h3 class="title"><a name="stylestructure"></a>Structure</h3></div></div><p> 72 In general, you won't have to worry too much about structure, 73 because the templates provide you with an excellent example. 74 As a general rule, try to follow that structural example. 75 That means using links, hierarchical nesting, and, if 76 necessary, a glossary or index. You probably won't need to 77 use every available structural tag, but take advantage of 78 what DocBook provides you. 79 </p><p> 80 As to linking, there's some disagreement about whether to use 81 <tt><xref></tt> <tt><link></tt> 82 when you make links within your documents. You'll have to 83 decide, based on the different ways that they are presented 84 in output, which is more appropriate given the context. 85 Regardless of which you use, you should not forget to use 86 them. Help your readers find information that relevant to 87 the issue at hand. 88 </p><p> 89 The table of contents will be generated automatically, but 90 you will probably have to develop your own index if you wish 91 to have one. The Nautilus Help Browser will have new, and 92 currently unknown, indexing capabilities, so index style and 93 structure are still under discussion. The GNOME User's Guide 94 will contain a glossary in its next versions; unless you're 95 writing a<tt><book></tt>, it will probably be best to 96 contribute to that rather than developing your own. 97 </p></div><div class="sect2"><a name="stylegrammar"></a><div class="titlepage"><div><h3 class="title"><a name="stylegrammar"></a>Grammar and Spelling</h3></div></div><p> 98 Nobody expects you to be perfect; they just expect the 99 documentation for their software to be error-free. That means 100 that, in the same way that developers look for bugs and accept 101 bug reports, writers must check for errors in their documents. 102 Poor grammar, bad spelling, and gross technical errors in 103 draft documents are fine. However, if those problems show up 104 in a "real" release, they can count against the credibility of 105 GNOME and Linux. They'll also make you look bad. 106 </p><p> 107 There is no substitute for a human proofreader; use a 108 spell-check program, then read it over yourself, and then find 109 someone else to help you. Other GDP members are, of course, 110 willing and able to help you, but non-writers are often at 111 least as helpful. 112 </p><p> 113 Proofreading documents is both a also a good way to 114 familiarize yourself with documentation, and it certainly 115 makes you valuable to the GDP. Help other writers proof their 116 documents, and they will help you with yours. 117 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a href="indexs11.html">Prev</a>�</td><td width="20%" align="center"><a href="index.html">Home</a></td><td width="40%" align="right">�<a href="indexs13.html">Next</a></td></tr><tr><td width="40%" align="left">Referring to Other GNOME Documentation (coming in 118 GNOME-2.0)�</td><td width="20%" align="center"><a href="index.html">Up</a></td><td width="40%" align="right">�Teamwork</td></tr></table></div></body></html> 119