From d5278866fd29dad1b71f899ac1061670958061ac Mon Sep 17 00:00:00 2001
From: Astrid Elocson <aelocson@gmail.com>
Date: Sun, 11 Jan 2015 19:03:21 +0000
Subject: [PATCH 1/2] Move style guide tiddlers to their own folder

---
 .../tiddlers/{about => styleguide}/Documentation Style Guide.tid  | 0
 .../tiddlers/{about => styleguide}/Instruction Tiddlers.tid       | 0
 .../tw5.com/tiddlers/{about => styleguide}/Reference Tiddlers.tid | 0
 editions/tw5.com/tiddlers/{about => styleguide}/Spelling.tid      | 0
 .../tiddlers/{about => styleguide}/Technical Prose Style.tid      | 0
 .../tw5.com/tiddlers/{about => styleguide}/Tiddler Structure.tid  | 0
 .../Tiddler Titles.tid => styleguide/Tiddler Title Policy.tid}    | 0
 editions/tw5.com/tiddlers/{about => styleguide}/Typography.tid    | 0
 8 files changed, 0 insertions(+), 0 deletions(-)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Documentation Style Guide.tid (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Instruction Tiddlers.tid (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Reference Tiddlers.tid (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Spelling.tid (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Technical Prose Style.tid (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Tiddler Structure.tid (100%)
 rename editions/tw5.com/tiddlers/{about/Tiddler Titles.tid => styleguide/Tiddler Title Policy.tid} (100%)
 rename editions/tw5.com/tiddlers/{about => styleguide}/Typography.tid (100%)

diff --git a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid b/editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Documentation Style Guide.tid
rename to editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid
diff --git a/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid b/editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid
rename to editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid
diff --git a/editions/tw5.com/tiddlers/about/Reference Tiddlers.tid b/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Reference Tiddlers.tid
rename to editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
diff --git a/editions/tw5.com/tiddlers/about/Spelling.tid b/editions/tw5.com/tiddlers/styleguide/Spelling.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Spelling.tid
rename to editions/tw5.com/tiddlers/styleguide/Spelling.tid
diff --git a/editions/tw5.com/tiddlers/about/Technical Prose Style.tid b/editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Technical Prose Style.tid
rename to editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid
diff --git a/editions/tw5.com/tiddlers/about/Tiddler Structure.tid b/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Tiddler Structure.tid
rename to editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid
diff --git a/editions/tw5.com/tiddlers/about/Tiddler Titles.tid b/editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Tiddler Titles.tid
rename to editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid
diff --git a/editions/tw5.com/tiddlers/about/Typography.tid b/editions/tw5.com/tiddlers/styleguide/Typography.tid
similarity index 100%
rename from editions/tw5.com/tiddlers/about/Typography.tid
rename to editions/tw5.com/tiddlers/styleguide/Typography.tid

From 76a3a44d4c8bd88d9cec8e53a2c4a7f8ed1596de Mon Sep 17 00:00:00 2001
From: Astrid Elocson <aelocson@gmail.com>
Date: Sun, 11 Jan 2015 19:04:14 +0000
Subject: [PATCH 2/2] Introduce documentation macros

---
 .../styleguide/Documentation Macros.tid       | 140 ++++++++++++++++++
 .../styleguide/Documentation Style Guide.tid  |  13 +-
 .../styleguide/Instruction Tiddlers.tid       |  55 +++----
 .../styleguide/Reference Tiddlers.tid         |  31 ++--
 .../tw5.com/tiddlers/styleguide/Spelling.tid  |   8 +-
 .../styleguide/Technical Prose Style.tid      |  10 +-
 .../tiddlers/styleguide/Tiddler Structure.tid |   8 +-
 .../styleguide/Tiddler Title Policy.tid       |  25 +++-
 .../tiddlers/styleguide/Typography.tid        |  17 +--
 .../tw5.com/tiddlers/system/doc-macros.tid    |  38 +++++
 .../tw5.com/tiddlers/system/doc-styles.tid    |  57 +++++++
 11 files changed, 322 insertions(+), 80 deletions(-)
 create mode 100644 editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
 create mode 100644 editions/tw5.com/tiddlers/system/doc-macros.tid
 create mode 100644 editions/tw5.com/tiddlers/system/doc-styles.tid

diff --git a/editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid b/editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
new file mode 100644
index 000000000..65f96709f
--- /dev/null
+++ b/editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid	
@@ -0,0 +1,140 @@
+created: 20150110182600000
+title: Documentation Macros
+tags: [[Improving TiddlyWiki Documentation]]
+
+The following macros are used throughout the documentation.
+
+!General
+
+|!Macro |!Used for |!Example |
+|doc-def |the defining instance of a term |<<doc-def widget>> |
+|doc-em |minor emphasis within a sentence |<<doc-em not>> |
+|doc-ph |a placeholder for the user to fill in |<<doc-ph tagname>> |
+|doc-strong |major emphasis within a tiddler |<<doc-strong Important!>> |
+|doc-w |a mention of an ordinary word or phrase |<<doc-w "hello world">> |
+
+!Tiddlers and fields
+
+|!Macro |!Used for |!Example |
+|doc-tiddler |a tiddler title|<<doc-tiddler Example>> |
+|doc-tag |a tag |<<doc-tag Example>> |
+|doc-field|a field name|<<doc-field example>> |
+|doc-field-value|a field value|<<doc-field-value "example value">> |
+|doc-var|a variable or macro name|<<doc-var currentTiddler>> |
+|doc-widget|a widget name|<<doc-widget list>> |
+
+!Links
+
+|!Macro |!Used for |!Example |
+|doc-link |a link containing WikiText |<<doc-link "^^an^^ ~~example~~" Example>> |
+|doc-clink |a code link |<<doc-clink `<$list>` ListWidget>> |
+
+!User interface
+
+|!Macro |!Used for |!Example |
+|doc-key |a key on the keyboard |<<doc-key Escape>> |
+|doc-key-combo |a key combination |<<doc-key-combo Ctrl Enter>> |
+|doc-input |text entered by the user |<<doc-input "npm install -g tiddlywiki">> |
+|doc-output |text output by the system |<<doc-output "Serving on 127.0.0.1:8080">> |
+
+!Tabs
+
+|!Macro |!Used for |!Example |
+|doc-sidebar-tab |the name of a sidebar tab |<<doc-sidebar-tab More>> |
+|doc-more-tab |the name of a subtab of the More tab |<<doc-more-tab Shadows>> |
+|doc-info-tab |the name of a tiddler info tab |<<doc-info-tab Fields>> |
+|doc-controlpanel-tab |the name of a Control Panel tab |<<doc-controlpanel-tab Settings>> |
+|doc-advancedsearch-tab |the name of an Advanced Search tab |<<doc-advancedsearch-tab Filter>> |
+|doc-toc-tab |name of the tw5.com TOC tab |<<doc-toc-tab>> |
+|doc-example-tab |an example tab name |<<doc-example-tab "Notes">> |
+
+!!Parameters for doc-sidebar-tab
+
+|Open |<<doc-sidebar-tab Open>> |
+|Recent |<<doc-sidebar-tab Recent>> |
+|Tools |<<doc-sidebar-tab Tools>> |
+|More |<<doc-sidebar-tab More>> |
+
+!!Parameters for doc-more-tab
+
+|All |<<doc-more-tab All>> |
+|Recent |<<doc-more-tab Recent>> |
+|Tags |<<doc-more-tab Tags>> |
+|Missing |<<doc-more-tab Missing>> |
+|Drafts |<<doc-more-tab Drafts>> |
+|Orphans |<<doc-more-tab Orphans>> |
+|Types |<<doc-more-tab Types>> |
+|System |<<doc-more-tab System>> |
+|Shadows |<<doc-more-tab Shadows>> |
+
+!!Parameters for doc-info-tab
+
+|Tools |<<doc-info-tab Tools>> |
+|References |<<doc-info-tab References>> |
+|Tagging |<<doc-info-tab Tagging>> |
+|List |<<doc-info-tab List>> |
+|Listed |<<doc-info-tab Listed>> |
+|Fields |<<doc-info-tab Fields>> |
+|Advanced |<<doc-info-tab Advanced>> |
+
+!!Parameters for doc-controlpanel-tab
+
+|Info |<<doc-controlpanel-tab Info>> |
+|Appearance |<<doc-controlpanel-tab Appearance>> |
+|Settings |<<doc-controlpanel-tab Settings>> |
+|Saving |<<doc-controlpanel-tab Saving>> |
+|Plugins |<<doc-controlpanel-tab Plugins>> |
+
+!!Parameters for doc-advancedsearch-tab
+
+|Standard |<<doc-advancedsearch-tab Standard>> |
+|System |<<doc-advancedsearch-tab System>> |
+|Shadows |<<doc-advancedsearch-tab Shadows>> |
+|Filter |<<doc-advancedsearch-tab Filter>> |
+
+!Buttons
+
+|!Macro |!Used for |!Example |
+|doc-button |a standard button name and icon |<<doc-button "new-tiddler">> |
+
+!!Parameters for doc-button
+
+!!!Tiddler toolbar
+
+|clone |<<doc-button "clone">> |
+|close |<<doc-button "close">> |
+|close-others |<<doc-button "close-others">> |
+|edit |<<doc-button "edit">> |
+|export-tiddler |<<doc-button "export-tiddler">> |
+|info |<<doc-button "info">> |
+|more-tiddler-actions |<<doc-button "more-tiddler-actions">> |
+|new-here |<<doc-button "new-here">> |
+|new-journal-here |<<doc-button "new-journal-here">> |
+|permalink |<<doc-button "permalink">> |
+
+!!!Edit-mode toolbar
+
+|cancel |<<doc-button "cancel">> |
+|delete |<<doc-button "delete">> |
+|save |<<doc-button "save">> |
+
+!!!Page toolbar
+
+|advanced-search |<<doc-button "advanced-search">> |
+|close-all |<<doc-button "close-all">> |
+|control-panel |<<doc-button "control-panel">> |
+|encryption |<<doc-button "encryption">> |
+|export-page |<<doc-button "export-page">> |
+|full-screen |<<doc-button "full-screen">> |
+|home |<<doc-button "home">> |
+|import |<<doc-button "import">> |
+|language |<<doc-button "language">> |
+|more-page-actions |<<doc-button "more-page-actions">> |
+|new-journal |<<doc-button "new-journal">> |
+|new-tiddler |<<doc-button "new-tiddler">> |
+|permaview |<<doc-button "permaview">> |
+|refresh |<<doc-button "refresh">> |
+|save-wiki |<<doc-button "save-wiki">> |
+|storyview |<<doc-button "storyview">> |
+|tag-manager |<<doc-button "tag-manager">> |
+|theme |<<doc-button "theme">> |
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid b/editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid
index 99ca0ef04..280ad68a7 100644
--- a/editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Documentation Style Guide.tid	
@@ -1,7 +1,7 @@
 created: 20140904164608166
-modified: 20140904164935351
+modified: 20150110181800000
 title: Documentation Style Guide
-tags: documenting [[Improving TiddlyWiki Documentation]]
+tags: [[Improving TiddlyWiki Documentation]]
 type: text/vnd.tiddlywiki
 
 The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience:
@@ -9,10 +9,13 @@ The documentation for ~TiddlyWiki tries to follow a consistent editorial style.
 * [[Instruction Tiddlers]]
 * [[Reference Tiddlers]]
 
-Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information.
+We keep the two areas distinct. This avoids overwhelming relative newcomers, while still providing quick access to the information that expert users need.
 
-* [[Tiddler Titles]]
+Additional topics:
+
+* [[Tiddler Title Policy]]
 * [[Tiddler Structure]]
 * [[Spelling]]
 * [[Typography]]
-* [[Technical Prose Style]]
+* [[Documentation Macros]]
+* [[Technical Prose Style]]
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid b/editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid
index 0270800ea..301b7c21b 100644
--- a/editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Instruction Tiddlers.tid	
@@ -1,38 +1,39 @@
-created: 20141226192500000
+created: 20150110101500000
+modified: 20150110181800000
 title: Instruction Tiddlers
-tags: documenting
+tags: [[Improving TiddlyWiki Documentation]]
 
-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.
+<<doc-def "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
+;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
+;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 <<doc-w "Find out more">> section at the end can offer related links
 
-* ''Exercise''
-** Accompanying a tutorial tiddler
-** Solution revealed on demand
+;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
+;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
+;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.
+Instruction tiddlers talk directly to the reader as <<doc-w 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".
+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 <<doc-w convenient>> or <<doc-w easy>>.
diff --git a/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid b/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
index d7380e442..8c1e5c84f 100644
--- a/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid	
@@ -1,25 +1,26 @@
 created: 20141226192500000
+modified: 20150110182100000
 title: Reference Tiddlers
-tags: documenting
+tags: [[Improving TiddlyWiki Documentation]]
 
-Reference tiddlers offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
+<<doc-def "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
+;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
+* <<doc-w "the template is specified as a tiddler">> rather than <<doc-w "specify the template as a tiddler">>
+* <<doc-w "the widget can be used for various purposes">> rather than <<doc-w "you can use the widget for various purposes">>
+* But <<doc-w "this widget has several possible uses">> is better, because it is less convoluted and 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.
+Most contracted verb forms are avoided in reference tiddlers. But those ending in <<doc-w "n't">> (<<doc-w "aren't">>, <<doc-w "doesn't">>, <<doc-w "hasn't">>, <<doc-w "isn't">>, etc) are acceptable, as they make it less easy to accidentally overlook the word <<doc-w not>>.
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/styleguide/Spelling.tid b/editions/tw5.com/tiddlers/styleguide/Spelling.tid
index 7049d85f5..020c20738 100644
--- a/editions/tw5.com/tiddlers/styleguide/Spelling.tid
+++ b/editions/tw5.com/tiddlers/styleguide/Spelling.tid
@@ -1,12 +1,12 @@
-created: 20141226192500000
+created: 20150110182900000
 title: Spelling
-tags: documenting
+tags: [[Improving TiddlyWiki Documentation]]
 
 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".
+Words like <<doc-w customise>> are spelled <<doc-w -ise>>, not <<doc-w -ize>>.
 
-Standard technical acronyms are written in upper case, without dots: `HTML`, not `html` or `H.T.M.L.`
+Standard technical acronyms are written in upper case, without dots: <<doc-w HTML>>, not <<doc-w html>> or <<doc-w H.T.M.L.>>
 
 Avoid arbitrarily abbreviating words and sentences. But the following abbreviations are acceptable:
 
diff --git a/editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid b/editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid
index 0f8f7465b..09022bed4 100644
--- a/editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Technical Prose Style.tid	
@@ -1,14 +1,14 @@
-created: 20141226192500000
+created: 20150110182900000
 title: Technical Prose Style
-tags: documenting
+tags: [[Improving TiddlyWiki Documentation]]
 
-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.
+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..."
+It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. <<doc-w "Execution of the macro is performed">> just means <<doc-w "The macro runs">>. <<doc-w "Your expectation might be...">> just means <<doc-w "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.
+Prefer the active voice by default: <<doc-w "Jane creates a tiddler">> rather than <<doc-w "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: <<doc-w "a tiddler is created">>. But it may be clearer to proceed from cause to effect and say <<doc-w "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.
 
diff --git a/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid b/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid
index 26ef86882..ed026cfb1 100644
--- a/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid	
@@ -1,15 +1,15 @@
-created: 20141226192500000
+created: 20150110183300000
 title: Tiddler Structure
-tags: documenting
+tags: [[Improving TiddlyWiki Documentation]]
 
 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.
+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]].
+Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[reference tiddlers|Reference Tiddlers]].
 
 The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.
diff --git a/editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid b/editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid
index ea93dd761..c779704b3 100644
--- a/editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid	
+++ b/editions/tw5.com/tiddlers/styleguide/Tiddler Title Policy.tid	
@@ -1,13 +1,22 @@
-created: 20141226192500000
-title: Tiddler Titles
-tags: documenting
+created: 20150110183300000
+modified: 20150110190400000
+title: Tiddler Title Policy
+tags: [[Improving TiddlyWiki Documentation]]
 
-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".
+Many documentation tiddlers, especially the [[reference ones|Reference Tiddlers]], are concerned with a single concept. Their titles should be succinct noun phrases like <<doc-tiddler "List Widget">> or <<doc-tiddler "Tiddler Fields">>.
 
-[[Reference Tiddlers]] have ~CamelCase nouns as their titles, e.g. ''~RevealWidget'', ''~CamelCase'', ''CSS''. The title is plural if it denotes a category, e.g. ''~KeyboardShortcuts'', ''~TiddlerFields''. Such categories are used to tag more specific tiddlers within the category.
+Each of the main words of such a title begins with a capital letter. Minor words such as <<doc-w and>>, <<doc-w or>>, <<doc-w the>>, <<doc-w to>> and <<doc-w with>> do not.
 
-Other tags usually consist of a single lowercase word. Avoid spaces in tags.
+Tags also follow this pattern.
 
-[[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.
+Titles of this kind are plural if they denote a category of items, e.g. <<doc-tiddler "Keyboard Shortcuts">> or <<doc-tiddler "Tiddler Fields">>. Such titles are used to tag more specific tiddlers within the category.
 
-How-to tiddlers have titles that begin with ''How to''.
+Where a concept is an item rather than a category, its tiddler has a singular title, e.g. <<doc-tiddler "List Widget">>, <<doc-tiddler "Tag Operator">>.
+
+Avoid starting a title with the word <<doc-w the>>.
+
+In the past, many tiddlers had CamelCase titles. This is gradually being phased out of the documentation to improve readability. ~CamelCase titles should no longer be used, even for tags, except in cases like <<doc-tiddler ~JavaScript>> where that is the standard spelling.
+
+[[Instruction tiddlers|Instruction Tiddlers]] often have longer titles that can be more complicated than just a noun phrase, e.g. <<doc-tiddler "Ten reasons to switch to ~TiddlyWiki">> These titles use sentence case, i.e. only the first word (and any proper names) starts with a capital letter.
+
+How-to tiddlers have titles that begin with <<doc-w "How to">>, e.g. <<doc-tiddler "How to edit a tiddler">>. Avoid titles like <<doc-tiddler "Editing tiddlers">>, because a less fluent English speaker could misunderstand that as the name of a category of tiddlers.
\ No newline at end of file
diff --git a/editions/tw5.com/tiddlers/styleguide/Typography.tid b/editions/tw5.com/tiddlers/styleguide/Typography.tid
index dabce5a9b..4efcd6bb2 100644
--- a/editions/tw5.com/tiddlers/styleguide/Typography.tid
+++ b/editions/tw5.com/tiddlers/styleguide/Typography.tid
@@ -2,22 +2,15 @@ created: 20141226192500000
 title: Typography
 tags: documenting
 
-Use ''bold'' when referring to:
+Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.
 
-* 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''"
+Be wary of arbitrarily applying raw bold or italic markup in a sentence. If there's a suitable macro, use that instead. If there isn't a suitable macro, write one or request one.
 
-''Bold'' is also used to make part or all of a sentence stand out from the rest of the tiddler.
+Use simple backticks (<code>`...`</code>) for fragments of WikiText.
 
-Use //italics// to give more subtle emphasis to a word or phrase.
+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 `…`.
 
-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 `…`
+Use `"` as the primary quotation mark, reserving `'` for the rare case of a nested quotation.
 
 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.
 
diff --git a/editions/tw5.com/tiddlers/system/doc-macros.tid b/editions/tw5.com/tiddlers/system/doc-macros.tid
new file mode 100644
index 000000000..ba564effc
--- /dev/null
+++ b/editions/tw5.com/tiddlers/system/doc-macros.tid
@@ -0,0 +1,38 @@
+title: $:/editions/tw5.com/doc-macros
+tags: $:/tags/Macro
+
+\define doc-if(cond,then,else) <$reveal type="nomatch" default="$cond$" text="">$then$</$reveal><$reveal type="match" default="$cond$" text="">$else$</$reveal>
+
+\define doc-def(_) <dfn class="doc-def">$_$</dfn>
+\define doc-em(_) <em class="doc-em">$_$</em>
+\define doc-strong(_) <strong class="doc-strong">$_$</strong>
+\define doc-ph(_) <var class="doc-ph">$_$</var>
+\define doc-w(_) "$_$"
+
+\define doc-tiddler(_) <code class="doc-tiddler">$_$</code>
+\define doc-tag(_) <code class="doc-tag">$_$</code>
+\define doc-field(_) <code class="doc-field">$_$</code>
+\define doc-field-value(_) <code class="doc-field-value">$_$</code>
+\define doc-var(_) <code class="doc-var">$_$</code>
+\define doc-widget(_) <code class="doc-widget">$_$</code>
+
+\define doc-link(_,to) <$link to="$to$">$_$</$link>
+\define doc-clink(_,to) <span class="doc-clink"><<doc-link """$_$""" "$to$">></span>
+
+\define doc-key(_) <span class="doc-key">$_$</span>
+\define doc-combo-key(_) <$macrocall $name="doc-if" cond="$_$" then="<<doc-key '$_$'>>"/>
+\define doc-key-combo(1,2,3,4) <<doc-combo-key "$1$">><<doc-if "$2$" +>><<doc-combo-key "$2$">><<doc-if "$3$" +>><<doc-combo-key "$3$">><<doc-if "$4$" +>><<doc-combo-key "$4$">>
+
+\define doc-input(_) `$_$`
+\define doc-output(_) `$_$`
+
+\define doc-tab(_) <span class="doc-tab">{{$_$!!caption}}</span>
+\define doc-sidebar-tab(_) <<doc-tab "$:/core/ui/SideBar/$_$">>
+\define doc-more-tab(_) <<doc-tab "$:/core/ui/MoreSideBar/$_$">>
+\define doc-info-tab(_) <<doc-tab "$:/core/ui/TiddlerInfo/$_$">>
+\define doc-controlpanel-tab(_) <<doc-tab "$:/core/ui/ControlPanel/$_$">>
+\define doc-advancedsearch-tab(_) <<doc-tab "$:/core/ui/AdvancedSearch/$_$">>
+\define doc-toc-tab() <<doc-tab "TableOfContents">>
+\define doc-example-tab(_) <span class="doc-tab">$_$</span>
+
+\define doc-button(_) <span class="doc-button">{{$:/core/ui/Buttons/$_$!!caption}}</span>
diff --git a/editions/tw5.com/tiddlers/system/doc-styles.tid b/editions/tw5.com/tiddlers/system/doc-styles.tid
new file mode 100644
index 000000000..658f1f02a
--- /dev/null
+++ b/editions/tw5.com/tiddlers/system/doc-styles.tid
@@ -0,0 +1,57 @@
+title: $:/editions/tw5.com/doc-styles
+tags: $:/tags/Stylesheet
+
+.doc-def {
+	font-style: normal;
+	font-weight: bold;
+}
+
+.doc-em {
+	font-style: italic;
+	font-variant: small-caps;
+	text-decoration: none;
+}
+
+.doc-strong {
+	color: <<colour alert-highlight>>;
+	font-style: normal;
+	font-weight: bold;
+}
+
+.doc-foreign {
+	font-style: italic;
+}
+
+.doc-ph {
+	border: none;
+	color: <<color foreground>>;
+	font-style: italic;
+}
+
+.doc-button,
+.doc-tab,
+.doc-tag,
+.doc-tiddler,
+.doc-field,
+.doc-field-value,
+.doc-var,
+.doc-widget {
+	background: <<color background>>;
+	border: none;
+	color: <<color very-muted-foreground>>;
+	font-weight: bold;
+	padding: 0;
+}
+
+.doc-button svg {
+	height: 1em;
+}
+
+.doc-key {
+	color: <<color very-muted-foreground>>;
+	font-weight: bold;
+}
+
+.doc-clink code {
+	color: <<colour tiddler-link-foreground>>;
+}
\ No newline at end of file