test

[hcoop/zz_old/ikiwiki] / StyleGuide.mdwn

diff --git a/StyleGuide.mdwn b/StyleGuide.mdwn
new file mode 100755 (executable)
index 0000000..547db41
--- /dev/null
+++ b/StyleGuide.mdwn
@@ -0,0 +1,65 @@
+#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