Personal tools

HaskellWiki:Guidelines

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(text about redundant occurences of the word “Haskell” removed)
m (Corrected typo)
 
(2 intermediate revisions by 2 users not shown)
Line 12: Line 12:
   
 
These are some guidelines for page titles:
 
These are some guidelines for page titles:
# Page titles not only affect a page's URL but they are also shown at the top of the page. Therefore, it is important that a page title is a title, not a mnemonic path name. I strongly doubt that we need such mnemonic names but if they are introduced they should denote only redirects to the actual page.
+
; No CamelCase
# On the other hand, it is good if titles are not unnecessarily long so that URLs have reasonable size.
+
: Page titles should be real titles like titles in a book or paper. Therefore, please don’t use CamelCase.
# Titles should use sentence-style capitalization (see [http://en.wikipedia.org/wiki/Capitalization#Headings_and_publication_titles]). Capitalizing more words seems to be only appropriate in larger documents like books. If slashes are used to denote hierarchy, each part of the hierarchical title should be handled as if it were a title itself, i.e., its first word should be capitalized.
+
; No mnemonic path names
  +
: Page titles not only affect a page’s URL but they are also shown at the top of the page. Therefore, it is important that a page title is a title, not a mnemonic path name. On the other hand, it is good if titles are not unnecessarily long so that URLs have reasonable size.
  +
; Sentence-style capitalization
  +
: Titles should use sentence-style capitalization (see [http://en.wikipedia.org/wiki/Capitalization#Headings_and_publication_titles]). Capitalizing more words seems to be only appropriate in larger documents like books. If slashes are used to denote hierarchy, each part of the hierarchical title should be handled as if it were a title itself, i.e., its first word should be capitalized.
   
===Page titles of "quiz" pages===
+
=== Page titles of “quiz” pages ===
The de-facto standard for quiz and contest pages is capitalization of each word in the page title, apparently contradicting the "Sentence case" guideline above. This is based on the idea that each of the quiz / contest / shootout problems is considered a proper name, hence should be capitalized. Similarly, the solutions are named "Solution John Doe", where the author of the solution is John Doe, again requiring capitalization of all words.
+
The de-facto standard for quiz and contest pages is capitalization of each word in the page title, apparently contradicting the “sentence case” guideline above. This is based on the idea that each of the quiz/contest/shootout problems is considered a proper name, hence should be capitalized. Similarly, the solutions are named “Solution John Doe”, where the author of the solution is John Doe, again requiring capitalization of all words.
  +
  +
== Renaming of page titles ==
  +
When doing a significant renaming of a page, (i.e., something more than just correcting the case as per the guidelines), use the discussion page to suggest a new title and the reasons for it. After a reasonable amount of time, if there are no objections, go ahead and move/rename the page.
   
 
== Categories ==
 
== Categories ==
Line 24: Line 24:
 
introduced. Whenever possible, please classify your page under one of
 
introduced. Whenever possible, please classify your page under one of
 
the categories. For example, if you write a page about your new project,
 
the categories. For example, if you write a page about your new project,
you can add it to the [http://haskell.org/haskellwiki/Category:Applications Applications category]
+
you can add it to the [[Category:Applications|Applications category]]
by adding the following text to your page:
+
by adding <nowiki>[[Category:Applications]]</nowiki> to your page.
 
<haskell>
 
[[Category:Applications]]
 
</haskell>
 
   
 
All known categories are in the wiki special page [[Special:Categories]].
 
All known categories are in the wiki special page [[Special:Categories]].
Line 31: Line 31:
 
== Headlines ==
 
== Headlines ==
   
Level 1 headlines (the ones written as <code>= Headline =</code>) shall not be used. Instead, a headline which is logically at the top level shall be implemented as a level 2 headline (i.e, as <code>== Headline ==</code>). The reason is that the page title and the level 1 headlines are both implemented as <tt>h1</tt> elements in the page's HTML. They are distinguished by using different HTML classes indeed, but this distinction is too light. For example, a browser which doesn't support CSS would probably render page titles and level 1 headlines the same way.
+
Level 1 headlines (the ones written as <code>= Headline =</code>) shall not be used. Instead, a headline which is logically at the top level shall be implemented as a level 2 headline (i.e, as <code>== Headline ==</code>). The reason is that the page title and the level 1 headlines are both implemented as <tt>h1</tt> elements in the page’s HTML. They are distinguished by using different HTML classes indeed, but this distinction is too light. For example, a browser which doesn't support CSS would probably render page titles and level 1 headlines the same way.
   
 
Like page titles, headlines shall use sentence-style capitalization [http://en.wikipedia.org/wiki/Capitalization#Headings_and_publication_titles].
 
Like page titles, headlines shall use sentence-style capitalization [http://en.wikipedia.org/wiki/Capitalization#Headings_and_publication_titles].
Line 37: Line 37:
 
== Links ==
 
== Links ==
   
Please don't use the click here approach for inserting links. Instead, formulate your text as if you would put it on paper (where the request to click doesn't make sense) and markup parts of the text (often only single words) as links.
+
Please don’t use the click here approach for inserting links. Instead, formulate your text as if you would put it on paper (where the request to click doesn't make sense) and markup parts of the text (often only single words) as links.
   
 
== Code on the Wiki ==
 
== Code on the Wiki ==
Line 44: Line 44:
   
 
Code examples should be kept as small and relevant as possible.
 
Code examples should be kept as small and relevant as possible.
  +
 
=== Large blocks of code ===
 
=== Large blocks of code ===
   
Line 49: Line 50:
   
 
This will contribute to the readability of the page.
 
This will contribute to the readability of the page.
  +
 
== Punctuation ==
 
== Punctuation ==
   
Line 57: Line 59:
 
When editing the wiki, the bottom of the editing page has a place to put a summary. It is considered good form to put a one line comment about any changes you are making. As well, you have the capability to mark an edit as ''minor''. Please use this only for changing format, spelling, fixing bad links or minor word re-arrangement. It should not be used when adding whole new sections, a significant number of links, new pages or rewrites of the page.
 
When editing the wiki, the bottom of the editing page has a place to put a summary. It is considered good form to put a one line comment about any changes you are making. As well, you have the capability to mark an edit as ''minor''. Please use this only for changing format, spelling, fixing bad links or minor word re-arrangement. It should not be used when adding whole new sections, a significant number of links, new pages or rewrites of the page.
   
[[Help:Editing|Information]] on editor support for the Haskell wiki.
+
There is special [[Help:Editing|information on editor support]] for the Haskell wiki.

Latest revision as of 10:12, 3 June 2012

Here you will find guidelines for editing this wiki.

Contents

[edit] 1 General principles

Please bear in mind that our first audience is those expecting a web-site on Haskell and not necessarily interested in this wiki thing. The default style, for instance, tries to make the wiki-ness as discreet as possible for readers not logged in.

[edit] 2 Page structure

There shall not be a single top level section. If you divide a page into sections, please introduce multiple sections at the top level. That means, the sections should form a true forest instead of just a tree. Using a single top level section is very untypical and is also not needed for giving the whole text a headline since there is the page title for this issue.

[edit] 3 Page titles

These are some guidelines for page titles:

No CamelCase
Page titles should be real titles like titles in a book or paper. Therefore, please don’t use CamelCase.
No mnemonic path names
Page titles not only affect a page’s URL but they are also shown at the top of the page. Therefore, it is important that a page title is a title, not a mnemonic path name. On the other hand, it is good if titles are not unnecessarily long so that URLs have reasonable size.
Sentence-style capitalization
Titles should use sentence-style capitalization (see [1]). Capitalizing more words seems to be only appropriate in larger documents like books. If slashes are used to denote hierarchy, each part of the hierarchical title should be handled as if it were a title itself, i.e., its first word should be capitalized.

[edit] 3.1 Page titles of “quiz” pages

The de-facto standard for quiz and contest pages is capitalization of each word in the page title, apparently contradicting the “sentence case” guideline above. This is based on the idea that each of the quiz/contest/shootout problems is considered a proper name, hence should be capitalized. Similarly, the solutions are named “Solution John Doe”, where the author of the solution is John Doe, again requiring capitalization of all words.

[edit] 4 Renaming of page titles

When doing a significant renaming of a page, (i.e., something more than just correcting the case as per the guidelines), use the discussion page to suggest a new title and the reasons for it. After a reasonable amount of time, if there are no objections, go ahead and move/rename the page.

[edit] 5 Categories

In order to ease navigation in the wiki, several categories are introduced. Whenever possible, please classify your page under one of the categories. For example, if you write a page about your new project, you can add it to the by adding [[Category:Applications]] to your page.

All known categories are in the wiki special page Special:Categories.

[edit] 6 Headlines

Level 1 headlines (the ones written as = Headline =) shall not be used. Instead, a headline which is logically at the top level shall be implemented as a level 2 headline (i.e, as == Headline ==). The reason is that the page title and the level 1 headlines are both implemented as h1 elements in the page’s HTML. They are distinguished by using different HTML classes indeed, but this distinction is too light. For example, a browser which doesn't support CSS would probably render page titles and level 1 headlines the same way.

Like page titles, headlines shall use sentence-style capitalization [2].

[edit] 7 Links

Please don’t use the click here approach for inserting links. Instead, formulate your text as if you would put it on paper (where the request to click doesn't make sense) and markup parts of the text (often only single words) as links.

[edit] 8 Code on the Wiki

As this site is about Haskell, there will obviously be cases where you need to include Haskell (or other) code. Use the appropriate tags for the language (<hask> and </hask> for inline Haskell, <haskell> and </haskell> for full blocks.) See, for example, HaskellWiki:Style test.

Code examples should be kept as small and relevant as possible.

[edit] 8.1 Large blocks of code

Rarely will people wade through a large piece of code, unless they are looking for something to implement or actually use. For those cases, consider using the Wiki file upload capability to load the source code and then provide a link to that on the page. As an example, see the Alex/Wrapper monadUser page.

This will contribute to the readability of the page.

[edit] 9 Punctuation

If would be great if you would use the punctuation symbols which are used in professional documents like “, ” and — instead of their ASCII workarounds like " and -. If you use an X server with a keymap like mine, you can get “ and ” with AltGr + V and AltGr + B.

[edit] 10 Editing

When editing the wiki, the bottom of the editing page has a place to put a summary. It is considered good form to put a one line comment about any changes you are making. As well, you have the capability to mark an edit as minor. Please use this only for changing format, spelling, fixing bad links or minor word re-arrangement. It should not be used when adding whole new sections, a significant number of links, new pages or rewrites of the page.

There is special information on editor support for the Haskell wiki.