mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-14 05:44:50 +00:00
40d21f607a
I was cloning this docs tiddler to experiment with docs for a new widget and noticed some punctuation inconsistencies
19 lines
1.4 KiB
Plaintext
19 lines
1.4 KiB
Plaintext
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.
|