|
|
| (133 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| | This page contains information on how one should edit this wiki, eg: best practices, protocols, templates and the like. | | This page contains information on how one should edit this wiki, eg: best practices, protocols, templates and the like. |
| | | | |
| − | == Semantic mediawiki extension ==
| + | These pages are a highly recommended read: |
| − | 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:
| + | ; [[Help:Recommendations for editors|Recommendations for editors]] |
| − | | + | : How to configure your account and to make sure your information gets displayed correctly. |
| − | : <nowiki>[[competence::Python]]</nowiki> to make [[competence::Python]]
| + | ; [[Help:Tutorial|Oh God how does any of this work (Tutorial)]] |
| − | | + | : Quickly get up to speed with adding content. Has a nifty [[Help:Tutorial#Self-education|Self-education]] section that helps you discover exactly how things work around here. |
| − | and the search/generate syntax is equally straightforward | + | ; [[Help:Content policy|Content policy]] |
| − | | + | : What goes onto the wiki and what does not. |
| − | : <nowiki>{{#ask: [[Category:Software]] [[Category:Bioinformatics]] |?centre }}</nowiki> to make ''redacted, do not use before the extension is properly installed, or it may mess up the page's categories''
| + | ; [[Help:Naming protocol|Naming protocol]] |
| − | | + | : How to choose and spell names, terms, titles and the like. |
| − | as long as we do not let nomenclature run rampant and diverge (see: the problem with the semantic web).
| + | ; [[Help:Creating pages|Creating pages]] |
| | + | : Helpful guides to creating pages. Contains nifty stuff with templates and examples that will reduce the amount of work you'll have to do. |
| | + | ; [[:Category:Example page|Example pages]] |
| | + | : Your first stop for creating pages. |
| | + | ; [[Help:Categories and properties|Categories and properties]] |
| | + | : What they are, how they are used, and how to create new ones. |
| | + | ; [[Help:Editing|Editing help]] |
| | + | : Help with syntax, formatting and other practicalities. |
| | | | |
| | === Notice === | | === 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)]].
| + | This site has a lot of dynamically generated content, making heavy use of templates and the [http://semantic-mediawiki.org semantic mediawiki] extension. If anything looks broken or incorrect, please use the corresponding talk page to notify the person responsible. If all else fails, please notify [[User_talk: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 "Applications expert" and your research area (at least one, eg "Bioinformatics").
| |
| − | # List your special competences using verbatim semantic medawiki property tags, like so <nowiki>[[competence::Python]]</nowiki> to make e.g: [[competence::Python]], note double colons.
| |
| − | | |
| − | | |
| − | == Naming scheme and protocol ==
| |
| − | | |
| − | === Titles, headings and names ===
| |
| − | 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 which should be a capital letter, like so:
| |
| − | Recommendations for editors
| |
| − | Editing policies
| |
| − | Application experts
| |
| − | Category:Research area
| |
| − | Property:Competence
| |
| − | | |
| − | Mediawiki automatically capitalises the first letter of all names, which has the benefit that one can readily type most markup in all lowercase, like so:
| |
| − | <nowiki>[[competence::python]], [[category:research area]]</nowiki>, etc...
| |
| − | | |
| − | Widely accepted acronyms like SNIC, NSC or HMMER are of course exceptions from this rule, and should be in all uppercase.
| |
| − | | |
| − | === Application experts ===
| |
| − | Are spelled as such, or as such: "application expert". All lowercase in plain text, capitalized A in headings. All other spellings are in error. If you see one, change it.
| |
| − | | |
| − | For motivation:
| |
| − | # This is the way it's spelled in the [http://www.e-science.se/sites/default/files/serc_application_small.pdf| original research grant application].
| |
| − | # It is not analogous to Systems experts, Physics experts or Gymnastics experts. Appliction is not a field per se. Besides: see Kung-fu expert.
| |
| − | # 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, make content harder to find, and that will just plainly 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 [http://semantic-mediawiki.org| 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).
| |
| − | | |
| − | * '''Do not invent categories and properties recklessly!''' Check these lists first, to see if any of the already existing ones may suit your needs:
| |
| − | ** [[Special:Categories]]
| |
| − | ** [[Special:Properties]]
| |
| − | * '''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:
| |
| − | ** [[Special:UncategorizedCategories]]
| |
| − | : 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 the property mean, exactly?''' What does it entail? How should it be used? Add a brief and unambiguous description to the property page (eg: [[Property:Competence]]).
| |
| − | | |
| − | == best practices ==
| |
| − | | |
| − | | |
| − | == page designs / templates ==
| |
| − | | |
| − | | |
| − | == subscription lists ==
| |
| − | | |
| − | | |
| − | == help links ==
| |
