mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-06-25 23:03:15 +00:00
Initial expansion of the Documentation Style Guide
This commit is contained in:
parent
7abe9aa53d
commit
421d75a207
|
@ -1,69 +1,18 @@
|
||||||
created: 20140904164608166
|
created: 20140904164608166
|
||||||
modified: 20140904164935351
|
modified: 20140904164935351
|
||||||
title: Documentation Style Guide
|
title: Documentation Style Guide
|
||||||
tags: Improving TiddlyWiki Documentation
|
tags: documenting
|
||||||
type: text/vnd.tiddlywiki
|
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]].
|
Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information.
|
||||||
|
|
||||||
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"""
|
|
||||||
>>
|
|
||||||
|
|
||||||
|
* [[Tiddler Titles]]
|
||||||
|
* [[Tiddler Structure]]
|
||||||
|
* [[Spelling]]
|
||||||
|
* [[Typography]]
|
||||||
|
* [[Technical Prose Style]]
|
||||||
|
|
Loading…
Reference in New Issue
Block a user