TiddlyWiki5/editions/tw5.com/tiddlers/styleguide/Typography.tid

created: 20141226192500000
modified: 20150117152559000
title: Typography
tags: documenting

Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.

Be wary of arbitrarily applying raw bold or italic markup in a sentence. If there's a suitable macro, use that instead. If there isn't a suitable macro, write one or request one.

Use simple backticks (<code>&#96;...&#96;</code>) for fragments of WikiText, but not for the names of things like fields and widgets. These have their own macros.

To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`.

Use `"` as the primary quotation mark, reserving `'` for the rare case of a nested quotation.

Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.

Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.

It is very rarely necessary to use an exclamation mark in professional documentation.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
+								created: 20141226192500000
-												Overhaul the filter operator documentation: part 1

											
										
										
											2015-01-18 18:39:00 +00:00
+								modified: 20150117152559000
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
+								title: Typography
 								tags: documenting
-												Introduce documentation macros

											
										
										
											2015-01-11 19:04:14 +00:00
+								Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
-												Introduce documentation macros

											
										
										
											2015-01-11 19:04:14 +00:00
+								Be wary of arbitrarily applying raw bold or italic markup in a sentence. If there's a suitable macro, use that instead. If there isn't a suitable macro, write one or request one.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
-												Overhaul the filter operator documentation: part 1

											
										
										
											2015-01-18 18:39:00 +00:00
+								Use simple backticks (<code>&#96;...&#96;</code>) for fragments of WikiText, but not for the names of things like fields and widgets. These have their own macros.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
-												Introduce documentation macros

											
										
										
											2015-01-11 19:04:14 +00:00
+								To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
-												Introduce documentation macros

											
										
										
											2015-01-11 19:04:14 +00:00
+								Use `"` as the primary quotation mark, reserving `'` for the rare case of a nested quotation.
-												Create Typography.tid
											
										
										
											2014-12-26 19:31:18 +00:00
 								Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
 								Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
 								It is very rarely necessary to use an exclamation mark in professional documentation.