Difference between revisions of "Help:Naming protocol"

From SNIC Documentation
Jump to: navigation, search
Line 1: Line 1:
 +
In wikis, stringent spelling of names is always important, and doubly so on the snicdocs wiki, since it relies heavily upon the [http://semantic-mediawiki.org semantic mediawiki] extension, which enables doing very neat stuff like dynamic generation of lists, tables and mashups based on tagged data in ordinary wiki pages.
 +
 +
The annotation is unobtrusive, e.g:
 +
 +
: I am competent with <nowiki>[[expertise::Python]]</nowiki>.
 +
 +
to note that this page (or rather the person described by this page) is competent in Python. The search/generate syntax is equally straightforward
 +
 +
: <nowiki>{{#ask: [[Category:Software]] [[Category:Bioinformatics]] |?centre }}</nowiki>
 +
 +
However, in order to retain relevance it is highly important that we do not let nomenclature run rampant and diverge (see: the problem with the semantic web).
 +
 +
=== Notice ===
 +
In case the examples appear in red, or if you see similar broken links with double colons in them in other places on the wiki, '''''do not edit the links'''''. They appear because you have happened to come across the pages before we have managed to install the semantic mediawiki extension properly on our production server.  This problem should disappear very shortly, and if it persists beyond your definition of shortly, it may help to edit the page, do nothing, and click save, to prod mediawiki to regenerate the links. If nothing works, please notify [[User:Joel Hedlund (NSC)]].
 +
 +
 
== Titles, headings and names ==
 
== Titles, headings and names ==
 
Don't use too generic page titles, such as Introduction, Help, etc. Make your titles as descriptive as possible.
 
Don't use too generic page titles, such as Introduction, Help, etc. Make your titles as descriptive as possible.
Line 34: Line 50:
  
 
Why does this matter? It matters because Wiki. We need 100% consistent naming, or else content that should be sorted together will end up separated for stupid reasons, and that will make the site harder to navigate and make content harder to find, and that will just plain make things look bad.
 
Why does this matter? It matters because Wiki. We need 100% consistent naming, or else content that should be sorted together will end up separated for stupid reasons, and that will make the site harder to navigate and make content harder to find, and that will just plain make things look bad.
 
== Semantic mediawiki extension ==
 
The snicdocs wiki uses the [http://semantic-mediawiki.org semantic mediawiki] extension, which enables nifty things like dynamic generation of lists, tables and mashups based on tagged data in ordinary wiki pages. The annotation is unobtrusive, e.g:
 
 
: I am competent with <nowiki>[[expertise::Python]]</nowiki>.
 
 
to note that this page (or rather the person described by this page) is competent in Python. The search/generate syntax is equally straightforward
 
 
: <nowiki>{{#ask: [[Category:Software]] [[Category:Bioinformatics]] |?centre }}</nowiki>
 
 
However, we must not let nomenclature run rampant and diverge (see: the problem with the semantic web).
 
 
=== Notice ===
 
In case the examples appear in red, or if you see similar broken links with double colons in them in other places on the wiki, '''''do not edit the links'''''. They appear because you have happened to come across the pages before we have managed to install the semantic mediawiki extension properly on our production server.  This problem should disappear very shortly, and if it persists beyond your definition of shortly, it may help to edit the page, do nothing, and click save, to prod mediawiki to regenerate the links. If nothing works, please notify [[User:Joel Hedlund (NSC)]].
 

Revision as of 21:28, 27 June 2011

In wikis, stringent spelling of names is always important, and doubly so on the snicdocs wiki, since it relies heavily upon the semantic mediawiki extension, which enables doing very neat stuff like dynamic generation of lists, tables and mashups based on tagged data in ordinary wiki pages.

The annotation is unobtrusive, e.g:

I am competent with [[expertise::Python]].

to note that this page (or rather the person described by this page) is competent in Python. The search/generate syntax is equally straightforward

{{#ask: [[Category:Software]] [[Category:Bioinformatics]] |?centre }}

However, in order to retain relevance it is highly important that we do not let nomenclature run rampant and diverge (see: the problem with the semantic web).

Notice

In case the examples appear in red, or if you see similar broken links with double colons in them in other places on the wiki, do not edit the links. They appear because you have happened to come across the pages before we have managed to install the semantic mediawiki extension properly on our production server. This problem should disappear very shortly, and if it persists beyond your definition of shortly, it may help to edit the page, do nothing, and click save, to prod mediawiki to regenerate the links. If nothing works, please notify User:Joel Hedlund (NSC).


Titles, headings and names

Don't use too generic page titles, such as Introduction, Help, etc. Make your titles as descriptive as possible.

Be very careful to get all names right. Since this is a wiki, misspelling (and Erroneous Capitalisation!) lead to duplication and potentially much backtracking at a later stage when someone has to merge diverged content.

Prefer UK English in names, despite the fact that we consciously and expressly refrain from enforcing UK English in plain text sitewide (since this in all honesty would never work anyway).

Capitalisation matters in mediawiki, to the point that you only get to have some control over it. Case in point: Category:Molecular dynamics and Category:molecular dynamics go to the same page, but Category:Molecular Dynamics does not (and don't you go create it!). Therefore:

All titles, headings and names, including category names and property names, should be in all lowercase, except the first character of the first word, which should be a capital letter. Headings, titles and names should never end with a full stop.

Widely accepted acronyms like SNIC, NSC, SeRC or HMMER are of course exceptions from these capitalisation rules, and should be in the case that everyone knows and expects them to be.

Examples:

Recommendations for editors
Editing policies
Application experts
Category:Research area
Property:Competence

Automatic capitalisation of first character

Mediawiki automatically capitalises the first letter of all names, with the benefit that one can readily type most markup in all lowercase, like so:

[[expertise::python]], [[category:research area]], etc...

However, semantic mediawiki sometimes gets all snooty over namespace capitalisation, so for now it's probably safest to do it right yourself and type e.g.

[[research area::Category:bioinformatics]], [[image::Image:uglymug.jpg]]

This bug has been reported (29536).

Spell it: application expert, systems expert

The term "application expert" is spelled as such, and likewise goes for the term "systems expert". All characters lowercase, except the very first character (A or S), which should be capitalized only where language rules or style so dictates (start of sentence, page titles, headings, wiki links, wiki names, etc...). All other spellings are in error. If you see one: change it.

Why does this matter? It matters because Wiki. We need 100% consistent naming, or else content that should be sorted together will end up separated for stupid reasons, and that will make the site harder to navigate and make content harder to find, and that will just plain make things look bad.