mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-28 11:00:27 +00:00
376b447570
@erwanm I ended up making some fairly extensive tweaks. One issue is that the (excellent) material you’ve provided on transclusion with templates covers very much the same ground as the existing TemplateTiddlers tiddler. The existing text was focused on transclusion with widgets; I think your material using transclusion notation is much easier to understand. I’ve also removed the exercises section. We don’t have exercises elsewhere in the documentation, so I think we need to make a conscious decision about whether we’re going to try to add them, and then do so consistently across the material. I also made some changes to bring the text into house style for consistency (which I’ve also tried to start documenting).
65 lines
2.2 KiB
Plaintext
65 lines
2.2 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, 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.
|
|
|
|
! 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.
|
|
|
|
<<style-guide
|
|
"""!! How to Configure Default Tiddlers"""
|
|
"""!! How to configure default tiddlers"""
|
|
>>
|
|
|