created: 20140904164608166 modified: 20140904164935351 title: Documentation Style Guide tags: Improving TiddlyWiki Documentation 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. ! Tone 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. !! 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. <>