mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-06-16 10:29:54 +00:00
Code Issues Releases Wiki Activity

Initial expansion of the Documentation Style Guide

Browse Source
This commit is contained in:
Astrid Elocson 2014-12-26 19:24:47 +00:00
parent 7abe9aa53d
commit 421d75a207
1 changed files with 10 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
editions/tw5.com/tiddlers/about/Documentation Style Guide.tid
View File

@ -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.
<<style-guide
"""!! How to Configure Default Tiddlers"""
"""!! How to configure default tiddlers"""
>>
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]]