1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-12-15 20:50:27 +00:00
TiddlyWiki5/editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
yaisog bfcb386343
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 18:00:04 +01:00

28 lines
1.4 KiB
Plaintext

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