TiddlyWiki5/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid

created: 20141226192500000
modified: 20230318160831470
tags: [[Improving TiddlyWiki Documentation]]
title: Reference Tiddlers

<<.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
** Widget documentation should follow the [[Widget Documentation Style Guide]]

;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:

* <<.word "the template is specified as a tiddler">> rather than <<.word "specify the template as a tiddler">>
* <<.word "the widget can be used for various purposes">> rather than <<.word "you can use the widget for various purposes">>
* But <<.word "this widget has several possible uses">> is better, because it is less convoluted and more succinct

Most contracted verb forms are avoided in reference tiddlers. But those ending in <<.word "n't">> (<<.word "aren't">>, <<.word "doesn't">>, <<.word "hasn't">>, <<.word "isn't">>, etc) are acceptable, as they make it less easy to accidentally overlook the word <<.word not>>.
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00			`created: 20141226192500000`
Restructure and optimize `CheckboxWidget` docs (#7362) * Restructure and optimize `CheckboxWidget` docs * Minor improvements * Use new tab macros and some reformatting * Fix bug in widget-attr-link tooltip * Minor layout tweaks * First try at a Widget Documentation Style Guide * Add new tabs-related macros to overview * Update CSS, add tm-scroll and rename macros * Avoid RSoE with tm-scroll, improve CSS for tab-links * Handle doc-tab-links within tab tiddlers better * Reflect macro name changes in their docs * Update Widget Doc Style Guide 2023-04-04 17:00:04 +00:00			`modified: 20230318160831470`
Introduce documentation macros 2015-01-11 19:04:14 +00:00			`tags: [[Improving TiddlyWiki Documentation]]`
Restructure and optimize `CheckboxWidget` docs (#7362) * Restructure and optimize `CheckboxWidget` docs * Minor improvements * Use new tab macros and some reformatting * Fix bug in widget-attr-link tooltip * Minor layout tweaks * First try at a Widget Documentation Style Guide * Add new tabs-related macros to overview * Update CSS, add tm-scroll and rename macros * Avoid RSoE with tm-scroll, improve CSS for tab-links * Handle doc-tab-links within tab tiddlers better * Reflect macro name changes in their docs * Update Widget Doc Style Guide 2023-04-04 17:00:04 +00:00			`title: Reference Tiddlers`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
Overhaul the filter operator documentation: part 1 2015-01-18 18:39:00 +00:00			`<<.def "Reference tiddlers">> offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
			`There are several subcategories:`

Introduce documentation macros 2015-01-11 19:04:14 +00:00			`;Concepts`
			`* With definitions, together forming a glossary`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
Introduce documentation macros 2015-01-11 19:04:14 +00:00			`;User manual`
			`* Presenting technical details of ~WikiText features`
			`* Subcategorised: messages, operators, widgets, etc`
Restructure and optimize `CheckboxWidget` docs (#7362) * Restructure and optimize `CheckboxWidget` docs * Minor improvements * Use new tab macros and some reformatting * Fix bug in widget-attr-link tooltip * Minor layout tweaks * First try at a Widget Documentation Style Guide * Add new tabs-related macros to overview * Update CSS, add tm-scroll and rename macros * Avoid RSoE with tm-scroll, improve CSS for tab-links * Handle doc-tab-links within tab tiddlers better * Reflect macro name changes in their docs * Update Widget Doc Style Guide 2023-04-04 17:00:04 +00:00			`** Widget documentation should follow the [[Widget Documentation Style Guide]]`
Introduce documentation macros 2015-01-11 19:04:14 +00:00
			`;Developer manual`
			`* Presenting technical details of ~TiddlyWiki's internal architecture`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
Introduce documentation macros 2015-01-11 19:04:14 +00:00			`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:`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
Overhaul the filter operator documentation: part 1 2015-01-18 18:39:00 +00:00			`* <<.word "the template is specified as a tiddler">> rather than <<.word "specify the template as a tiddler">>`
			`* <<.word "the widget can be used for various purposes">> rather than <<.word "you can use the widget for various purposes">>`
			`* But <<.word "this widget has several possible uses">> is better, because it is less convoluted and more succinct`
Create Reference Tiddlers.tid 2014-12-26 19:28:24 +00:00
Overhaul the filter operator documentation: part 1 2015-01-18 18:39:00 +00:00			`Most contracted verb forms are avoided in reference tiddlers. But those ending in <<.word "n't">> (<<.word "aren't">>, <<.word "doesn't">>, <<.word "hasn't">>, <<.word "isn't">>, etc) are acceptable, as they make it less easy to accidentally overlook the word <<.word not>>.`