Help:Editing policies
This page contains information on how one should edit this wiki, eg: best practices, protocols, templates and the like.
Contents
Semantic mediawiki extension
The snicdocs wiki uses the 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 [[competence::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, we must not let nomenclature run rampant and diverge (see: the problem with the semantic web). See Naming conventions below.
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, notify User:Joel Hedlund (NSC).
Recommendations for editors
Set up your watch lists and notifications
- Go to your preferences page and add your email.
- Configure your account so that pages you create automatically get added to your watchlist, and that notifications will go to your email.
- Check the list of Special:UnwatchedPages. Is it zero length? Otherwise something is wrong. Is any of your pages on there? Add them to your watch list.
Set up your user page correctly
- Tag your user page with the categories "application expert" and your research area (e.g: [[category:application expert]] [[category:computational chemistry]]).
- List your special competences in the clear using semantic medawiki property tags, like so [[competence::python]], note double colons. These competences may or may not overlap with your research area. A competence may be anything from programming languages to protocols to laboratory techniques, or something else entirely. Check out Property:Competence to see what other people have stated that they can do well. Maybe some of that applies to you as well?
- Tag your affiliation in the clear using a "centre" property tag, e.g: [[centre::NSC]], note spelling.
Naming scheme and protocol
Titles, headings and names
Be very careful to spell names right and to use correct capitalization (see below). Since this is a wiki, misspelling (and Wrong Capitalization!) lead to duplication and potentially much backtracking at a later stage when someone has to merge diverged content.
Capitalization 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 which should be a capital letter. Headings, titles and names should never end with a full stop. Examples:
Recommendations for editors Editing policies Application experts Category:Research area Property:Competence
However, note that mediawiki automatically capitalizes the first letter of all names, with the benefit that one can readily type most markup in all lowercase, like so:
[[competence::python]], [[category:research area]], etc...
Widely accepted acronyms like SNIC, NSC, SeRC or HMMER are of course exceptions from these capitalization rules, and should be in the case that everyone knows and expects them to be.
Spell it: application expert
The term "application expert" is spelled as such. All lowercase in plain text, capitalized A where 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.
For motivation, in decreasing order of relevance and increasing order of wordiness:
- This is the way it's spelled in the original research grant application.
- It is not analogous to systems experts, physics experts or gymnastics experts. Appliction is not a field per se. Besides: a Kung-fu expert might be able to set you straight.
- What application experts are experts on, is applying scientific algorithms and methods within their research area on high performance computing resources. Not just on the programs ("Applications") within that area.
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.
Categories and properties
The snicdocs wiki makes extensive use of categories, in part to simplify navigation for the users, but mostly because it permits straightforward creation of dynamically generated lists, tables and mashups using the semantic mediawiki extension. This, however, requires generous peppering of category and property tags onto wiki pages, using great restraint and strict discipline so that nomenclature does not run rampant and diverge (see: the problem with the semantic web).
Categories and properties have many things in common, however categories tend to be easier to use while properties are more flexible. Categories are big things. Adding categories to a page not only annotates the page to fall under those categories, but also and adds cross links and generates indexes. They are great for searching and finding, but less good for dynamic generation of content. For example, this table:
{#ask: [Category:Bioinformatics] [Category:Application expert] | ?centre | ?competence }}
could not be generated if the pages had not been annotated with properties stating that NSC is a place where a person works, and that these other things are in fact stuff they do good. The reason we don't drop categories alltogether is that categories have much added sweet sugary magic which would take a lot of boring effort to recreate with properties each time they're used in that fashion.
When to use one or the other should be quite obvious from gut feeling or looking at examples, but if in doubt: use categories. If using categories leads to awkwardness or unwanted effects, use properties.
Guidelines for creating new categories and properties:
- Do not invent categories and properties recklessly! Check these lists first, to see if any of the already existing ones may suit your needs:
- Use singular for names. E.g. Applications expert, Resource, Centre...
- Use descriptive and unambiguous names. Especially for properties. Keep in mind that these will be used to define searches and will also end up as headings in dynamically generated tables, unless other people do extra work to change it on each use.
- Are you creating a new subcategory? Categories can be nested in a DAG (tree) structure. Look at the current list of top categories:
- Does yours fit on that list, or will it fit better as a sub(-sub)-category? Drill down and see, and annotate your new category accordingly.
- What does it mean, exactly? What does it entail? How should it be used? Add a brief and unambiguous description to the property page (eg: Property:Competence, or Category:Application expert). Leave no room for misinterpretation, as this could potentailly could make your work useless.
- Use Type:Page (the default) for properties. You of course have lots of freedom when it comes to selecting a type for your property (cf. Special:Types), but generally, you should use the default unless it would be ludicrous to do so (e.g. it's a number, date, etc...). These are examples where the default "Type:Page" is the most useful: [[competence::python]], [[competence::MSA]], [[centre::NSC]]. In short, do not mess around with types and everything will probably work out OK.
Page designs and templates
Working on that now...
Editing help
Editing help is available here: Help:Editing.
