TiddlyWiki5/editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid

created: 20150110183300000
modified: 20210207124737959
title: Tiddler Structure
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.

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|Reference Tiddlers]].

Avoid periods at the end of list items, headings and table cell text.

The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.
Introduce documentation macros 2015-01-11 19:04:14 +00:00			`created: 20150110183300000`
Docs: Minor formatting tweaks I was cloning this docs tiddler to experiment with docs for a new widget and noticed some punctuation inconsistencies 2021-02-07 12:48:06 +00:00			`modified: 20210207124737959`
Create Tiddler Structure.tid 2014-12-26 19:29:41 +00:00			`title: Tiddler Structure`
Introduce documentation macros 2015-01-11 19:04:14 +00:00			`tags: [[Improving TiddlyWiki Documentation]]`
Create Tiddler Structure.tid 2014-12-26 19:29:41 +00:00
			`In accordance with the [[Philosophy of Tiddlers]], documentation tiddlers are typically short and interlinked.`

Introduce documentation macros 2015-01-11 19:04:14 +00:00			`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.`
Create Tiddler Structure.tid 2014-12-26 19:29:41 +00:00
			`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.`

Introduce documentation macros 2015-01-11 19:04:14 +00:00			`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]].`
Create Tiddler Structure.tid 2014-12-26 19:29:41 +00:00
Docs: Minor formatting tweaks I was cloning this docs tiddler to experiment with docs for a new widget and noticed some punctuation inconsistencies 2021-02-07 12:48:06 +00:00			`Avoid periods at the end of list items, headings and table cell text.`

Create Tiddler Structure.tid 2014-12-26 19:29:41 +00:00			`The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.`