diff --git a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid index c61584675..5da2174a9 100644 --- a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid +++ b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid @@ -1,69 +1,18 @@ created: 20140904164608166 modified: 20140904164935351 title: Documentation Style Guide -tags: Improving TiddlyWiki Documentation +tags: documenting type: text/vnd.tiddlywiki -The documentation for ~TiddlyWiki tries to follow a consistent style. The aim is to ensure that documentation from different authors reads consistently. +The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience: -! Tone +* [[Instruction Tiddlers]] +* [[Reference Tiddlers]] -Tutorial documentation may address the user as "you" for clarity and immediacy. Reference documentation should use a more formal [[passive voice|http://grammar.ccc.commnet.edu/grammar/passive.htm]]. - -For example, this would be reasonable for tutorial documentation: - -> You can add a new sidebar tab by creating a specially tagged tiddler - -But for reference documentation this would be better: - -> Tiddlers with a special tag are displayed as sidebar tabs - -! Tiddler Title Policy - -The following conventions govern how tiddler titles are composed: - -* Use lowercase single words for tags -** e.g. [[task]], [[demo]] -* Use CamelCase for definitions and concepts -** e.g. TiddlerFields, DeveloperDocs -* Use separate words for titles that are full phrases or sentences, such as FAQ, howtos or tasks -** e.g. [[How to build a TiddlyWiki5 from individual tiddlers]] -* Where TiddlyWiki or TiddlyWiki5 is used as a qualifier at the start of the title, always use separate words -** e.g. [[TiddlyWiki on Node.js]] - -! Spelling - -Use [[British spellings in preference to US spellings|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]]. - -! Abbreviations - -We try to avoid abbreviations for ordinary words, but the following are acceptable: - -* `e.g.` for ''for example'' -* `i.e.` for ''that is to say'' - -Note that the periods should not be omitted from these abbreviations. - -Technical abbreviations should be in upper case and omit periods: - -* ''HTML'', not ''html'' or ''H.T.M.L.'' -* ''CSS'', not ''css'' - -! Typographic Standards - -!! Referring to Titles, Fields, Tags - -* ''Titles'' of tiddlers should usually be typed as links -* ''Tag names'' should usually be typed as links -* ''Field names'' should be typed in bold: e.g. ''title'', ''tags'', ''caption'' -* ''Tab names'' should be typed in bold: e.g. ''Open'', ''Appearance'' - -!! Headings - -Initial capitalisation is preferred, where the initial letter of most words is capitalised. The exceptions are small conjunctions and prepositions like "and", "or", "the", "to", etc. - -<> +Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information. +* [[Tiddler Titles]] +* [[Tiddler Structure]] +* [[Spelling]] +* [[Typography]] +* [[Technical Prose Style]]