clone/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/TiddlyWiki/TiddlyWiki5.git synced 2026-05-05 09:26:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Introduce documentation macros

Browse Source
This commit is contained in:
Astrid Elocson
2015-01-11 19:04:14 +00:00
parent d5278866fd
commit 76a3a44d4c
11 changed files with 322 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
editions/tw5.com/tiddlers/styleguide/Tiddler Structure.tid
View File

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