Merge pull request #1289 from aelocson/patch-2

Expand the Document Style Guide

editions/tw5.com/tiddlers/about/Documentation Style Guide.tid

@@ -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]]

editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid

@@ -0,0 +1,38 @@
+created: 20141226192500000
+title: Instruction Tiddlers
+tags: documenting
+
+Instruction tiddlers talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user.
+
+Such tiddlers can be subcategorised as:
+
+* ''Welcome''
+** What is ~TiddlyWiki and why should I care?
+** Demonstrations of key features and benefits
+** Frequently asked questions
+** Examples of ~TiddlyWiki in the field
+** Information about the project itself
+
+* ''Tutorial''
+** An ordered presentation of material for beginners
+** Each tiddler introduces one new point or concept
+** Its main content contains very few links
+** A revealable "Further reading" section at the end can offer related links
+
+* ''Exercise''
+** Accompanying a tutorial tiddler
+** Solution revealed on demand
+
+* ''How-to''
+** A list of numbered steps for performing a small specific task
+** Concise, with links to reference tiddlers where appropriate
+** Often has a preamble to clarify the nature of the task
+
+* ''Example''
+** Accompanying a [[Reference Tiddler|Reference Tiddlers]]
+** Can contain explanations and similar commentary
+** Kept separate to keep the reference tiddler pure
+
+Instruction tiddlers talk directly to the reader as "you". They can be reasonably chatty.
+
+But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as "convenient" or "easy".

editions/tw5.com/tiddlers/about/Reference Tiddlers.tid

@@ -0,0 +1,25 @@
+created: 20141226192500000
+title: Reference Tiddlers
+tags: documenting
+
+Reference tiddlers offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
+
+There are several subcategories:
+
+* ''Concepts''
+** With definitions, together forming a glossary
+* ''User manual''
+** Presenting technical details of ~WikiText features
+** Subcategorised: messages, operators, widgets, etc
+* ''Developer manual''
+** Presenting technical details of ~TiddlyWiki's internal architecture
+
+Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable:
+
+* "the template can be specified as a tiddler" rather than "specify the template as a tiddler"
+* "the widget can be used for various purposes" rather than "you can use the widget for various purposes"
+* But "this widget has several possible uses" is better, because it is more succinct
+
+Contracted verb forms are normally avoided in reference tiddlers.
+
+To reduce the risk that the reader will overlook the word "not", it can be italicised.

editions/tw5.com/tiddlers/about/Spelling.tid

@@ -0,0 +1,16 @@
+created: 20141226192500000
+title: Spelling
+tags: documenting
+
+Because ~TiddlyWiki is of British origin, its English documentation uses [[British spelling in preference to US spelling|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]].
+
+Words like "customise" are spelled "-ise", not "-ize".
+
+Standard technical acronyms are written in upper case, without dots: `HTML`, not `html` or `H.T.M.L.`
+
+Avoid arbitrarily abbreviating words and sentences. But the following abbreviations are acceptable:
+
+|!Abbreviation |!Meaning |!Notes |
+|e.g. |for example |with a dot after each letter |
+|i.e. |that is to say |with a dot after each letter |
+|etc |and so on |without a dot |

editions/tw5.com/tiddlers/about/Technical Prose Style.tid

@@ -0,0 +1,15 @@
+created: 20141226192500000
+title: Technical Prose Style
+tags: documenting
+
+When writing an [[Instruction Tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
+
+Keep sentences short and simple. A clear technical sentence seldom contains more than one idea. It therefore avoids parenthetical information. Similarly, keep paragraph structure simple. A flat presentation is often easier to understand than a hierarchical one.
+
+It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. "Execution of the macro is performed" just means "The macro runs". "Your expectation might be..." just means "You might expect..."
+
+Prefer the active voice by default: "Jane creates a tiddler" rather than "a tiddler is created by Jane". The passive voice can be useful if you want the reader to focus on the action itself or its result: "a tiddler is created". But it may be clearer to proceed from cause to effect and say "this creates a tiddler" in the active voice.
+
+Documentation often presents two items that are parallel either by similarity or by difference. The reader will more easily detect such a pattern if you use the same sentence or phrase structure for both. But this must be balanced with the need to avoid monotony.
+
+Prefer precise instructions over woolly descriptions. If something has a name, use it. If something lacks a name, give it a tiddler.

editions/tw5.com/tiddlers/about/Tiddler Structure.tid

@@ -0,0 +1,15 @@
+created: 20141226192500000
+title: Tiddler Structure
+tags: documenting
+
+In accordance with the [[Philosophy of Tiddlers]], documentation tiddlers are typically short and interlinked.
+
+When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[Reference Tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details.
+
+Consistency of terminology is essential if the reader is not to become confused. Consistent typography and punctuation lend a professional quality to the documentation. Macros can improve the consistency and maintainability of the text.
+
+Use numbered lists for step-by-step instructions, and bullet points for lists whose order is arbitrary. Use a definition list in preference to a bulleted list if each bulleted item would begin with a term and a colon. If at all possible, avoid burdening the reader with a nested list.
+
+Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[Reference Tiddlers]].
+
+The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.

editions/tw5.com/tiddlers/about/Tiddler Titles.tid

@@ -0,0 +1,13 @@
+created: 20141226192500000
+title: Tiddler Titles
+tags: documenting
+
+Each of the main words of a tiddler title begins with a capital letter, but minor words such as "and", "or", "the", "to" and "with" do not. Avoid starting a tiddler with the word "the".
+
+[[Reference Tiddlers]] have ~CamelCase nouns as their titles, e.g. ''~RevealWidget'', ''~CamelCase'', ''CSS''. The title is plural if it denotes a category, e.g. ''~KeyboardShorcuts'', ''~TiddlerFields''. Such categories are used to tag more specific tiddlers within the category.
+
+Other tags usually consist of a single lowercase word. Avoid spaces in tags.
+
+[[Instruction Tiddlers]] have spaces between the words of their titles. Each word that contributes significantly to the meaning of the title starts with a capital letter. Words that are little more than structural signposts ("the", "and", "of", etc) are entirely lowercase.
+
+How-to tiddlers have titles that begin with ''How to''.

editions/tw5.com/tiddlers/about/Typography.tid

@@ -0,0 +1,26 @@
+created: 20141226192500000
+title: Typography
+tags: documenting
+
+Use ''bold'' when referring to:
+
+* Captions in ~TiddlyWiki's user interface:
+** "the ''Recent'' tab", "the ''Hide sidebar'' button"
+* Tiddler fields:
+** "the ''list'' field"
+* Example tiddlers and tags:
+** "create a tiddler called ''Super Soup Recipe'' with the tag ''cookery''"
+
+''Bold'' is also used to make part or all of a sentence stand out from the rest of the tiddler.
+
+Use //italics// to give more subtle emphasis to a word or phrase.
+
+Use `monospaced` text when a sentence contains a fragment of ~WikiText or a string that the user could type.
+
+Use the double quotation mark `"` as the basic one. It is easier to read on screen, and it avoids confusion with the apostrophe. To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`
+
+Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
+
+Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
+
+It is very rarely necessary to use an exclamation mark in professional documentation.