[hcoop/zz_old/ikiwiki] / StyleGuide.mdwn

#pragma section-numbers off\r
\r
This page explains the considerations that should be taken when writing pages in the HCoop wiki.\r
\r
[[TableOfContents]]\r
\r
= Template =\r
\r
Here's a basic template to apply when making new pages and revising old ones.\r
\r
{{{\r
Description of page.  I.e.: This page describes how to filter your email using\r
procmail and Exim.\r
\r
## Every page should have a table of contents\r
[[TableOfContents]]\r
\r
Remaining content of page, split into logical sections.\r
}}}\r
\r
= Section numbers =\r
\r
The following text, when placed at the beginning of a page, turns off numbering of headings.\r
\r
{{{\r
#pragma section-numbers off\r
}}}\r
\r
This should be used:\r
\r
 * If the page is the main page, or exactly one degree away from it, then you should include the following text at the very top of the page.\r
\r
 * On multi-page guides, such as DomTool.\r
\r
 * On other pages at the discretion of those who keep the wiki up-to-date.\r
\r
= Level of headings =\r
\r
If section numbers are turned off, then start with first-level headings.\r
\r
If section numbers are left on, then start with second-level headings.  The reason for this is that the numbers in front of first-level headings look ugly and distract from the content of the page.\r
  Why not hack on the style instead? --AdamChlipala\r
    Because the size of the normal unnumbered headings look about right.  Perhaps we should just turn section numbering off globally.  I could do that easily.  --MichaelOlson\r
\r
= Depth of headings =\r
\r
For the MemberManual, there should be no more than two levels of headings, so that the distinction beween different levels may be clearly seen.\r
\r
= Writing commands =\r
\r
If you are writing a command, then put it on a separate line, so that it stands out and is easy to copy and paste.\r
\r
Bad: {{{my-command foo bar}}}.\r
\r
Good:\r
\r
{{{\r
my-command foo bar\r
}}}\r
\r
= Point of view =\r
\r
It would be best to use "you" (second-person) when writing the MemberManual.\r
\r
For other pages, it probably doesn't matter.\r
Commit	Line	Data
ee25310d	1	#pragma section-numbers off\r
	2	\r
	3	This page explains the considerations that should be taken when writing pages in the HCoop wiki.\r
	4	\r
	5	[[TableOfContents]]\r
	6	\r
	7	= Template =\r
	8	\r
	9	Here's a basic template to apply when making new pages and revising old ones.\r
	10	\r
	11	{{{\r
	12	Description of page. I.e.: This page describes how to filter your email using\r
	13	procmail and Exim.\r
	14	\r
	15	## Every page should have a table of contents\r
	16	[[TableOfContents]]\r
	17	\r
	18	Remaining content of page, split into logical sections.\r
	19	}}}\r
	20	\r
	21	= Section numbers =\r
	22	\r
	23	The following text, when placed at the beginning of a page, turns off numbering of headings.\r
	24	\r
	25	{{{\r
	26	#pragma section-numbers off\r
	27	}}}\r
	28	\r
	29	This should be used:\r
	30	\r
	31	* If the page is the main page, or exactly one degree away from it, then you should include the following text at the very top of the page.\r
	32	\r
	33	* On multi-page guides, such as DomTool.\r
	34	\r
	35	* On other pages at the discretion of those who keep the wiki up-to-date.\r
	36	\r
	37	= Level of headings =\r
	38	\r
	39	If section numbers are turned off, then start with first-level headings.\r
	40	\r
	41	If section numbers are left on, then start with second-level headings. The reason for this is that the numbers in front of first-level headings look ugly and distract from the content of the page.\r
	42	Why not hack on the style instead? --AdamChlipala\r
	43	Because the size of the normal unnumbered headings look about right. Perhaps we should just turn section numbering off globally. I could do that easily. --MichaelOlson\r
	44	\r
	45	= Depth of headings =\r
	46	\r
	47	For the MemberManual, there should be no more than two levels of headings, so that the distinction beween different levels may be clearly seen.\r
	48	\r
	49	= Writing commands =\r
	50	\r
	51	If you are writing a command, then put it on a separate line, so that it stands out and is easy to copy and paste.\r
	52	\r
	53	Bad: {{{my-command foo bar}}}.\r
	54	\r
	55	Good:\r
	56	\r
	57	{{{\r
	58	my-command foo bar\r
	59	}}}\r
	60	\r
	61	= Point of view =\r
	62	\r
	63	It would be best to use "you" (second-person) when writing the MemberManual.\r
	64	\r
65	For other pages, it probably doesn't matter.\r