mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-07-14 16:04:21 +00:00
70 lines
2.4 KiB
Plaintext
70 lines
2.4 KiB
Plaintext
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. ''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"""
|
|
>>
|
|
|