|
|
| (47 intermediate revisions by the same user 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. |
| − | : I am competent with <nowiki>[[competence::Python]]</nowiki>. | + | ; [[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. |
| − | to note that this page (or rather the person described by this page) is competent in Python. 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> | + | ; [[Help:Naming protocol|Naming protocol]] |
| − | | + | : How to choose and spell names, terms, titles and the like. |
| − | However, we must not let nomenclature run rampant and diverge (see: the problem with the semantic web). See [[#Naming protocol|naming protocol]] below.
| + | ; [[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, 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)]].
| + | 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. Are any of your pages on there? Add them to your watch list.
| |
| − | # Feel very free to nag other people to watch pages. Unwatched pages rot and we do not want that.
| |
| − | | |
| − | === Set up your user page correctly ===
| |
| − | This will take some fiddling to get right. Upside is, you'll probably only do this once, and it'll make generation of dynamic tables so much easier for everyone later on. This section pretty much describes how to make your page function like [[User:Joel Hedlund (NSC)|Joel Hedlunds (NSC)]]. So:
| |
| − | | |
| − | * Tag your user page with your role, both as a category and a property, like so:
| |
| − | *:<nowiki>[[category:systems expert]] {{#set:role=category:systems expert}}</nowiki>
| |
| − | :this example sets the property quietly, which is probably for the best, unless you think <nowiki>[[role::Category:Application expert|Application expert]]</nowiki> looks nice (hint: no).
| |
| − | * Do the same with your research area if you are an application expert, e.g:
| |
| − | *:<nowiki>[[category:bioinformatics]] {{#set:research area=category:bioinformatics}}</nowiki>
| |
| − | * List your special competences in the clear, for example in a bullet list, and use the competence property tags, like so
| |
| − | *:<nowiki>* [[competence::python]]</nowiki>
| |
| − | *:<nowiki>* [[competence::mass spectrometry]]</nowiki>
| |
| − | *:<nowiki>* [[competence::flux capacitor calibration]]</nowiki>
| |
| − | : and note the 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 the full definition, along with a list of competences that other people have claimed to have. If some of those apply to you as well, yank them! If you create new competence, you should probably create the page that it points to, and add at least a little bit of information to it. A red competence does not look nice on your rap sheet.
| |
| − | * Tag your affiliation in the clear using a "centre" property tag, e.g: <nowiki>[[centre::NSC]]</nowiki>, note spelling.
| |
| − | * Create your talk page (Discussion), and add something inviting so that people will feel encouraged to talk to you, or just rip off someone else who said something nice. Remember that your talk page will likely be your primary form of contact for members of the general public who chance upon the wiki.
| |
| − | * You may want to add a visiting address using the office property, e.g: <nowiki>Office:<br/>[[office::Room G:159, House G, Campus Valla<br/>Linköpings Universitet<br/>SE-581 83 Linköping]]</nowiki>.
| |
| − | * You may also want to add one or more phone numbers using the phone property, e.g: <nowiki>Phone: [[phone::+46(0)13 282423 (office)]], [[phone::+46(0)734 607126 (mobile)]]</nowiki>.
| |
| − | * Note that we do not promote providing your direct email address here, and especially not using email type properties (e.g: <s><nowiki>[[email::user@server.net]]</nowiki></s>, do not use!), because no obfuscation is applied, and email addresses advertised in this manner are easily harvested by bots using the semantic mediawiki search interfaces.
| |
| − | | |
| − | == Naming protocol ==
| |
| − | | |
| − | === 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 Capitalization!) 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).
| |
| − | | |
| − | 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 of the first word, 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:
| |
| − | <nowiki>[[competence::python]], [[category:research area]]</nowiki>, 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, systems expert ===
| |
| − | The term "application expert" is spelled as such, and likewise goes for the term "systems expert". All lowercase in plain text, capitalized leading A or S 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.
| |
| − | | |
| − | 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 [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).
| |
| − | | |
| − | 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 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:
| |
| − | | |
| − | : <nowiki>{{#ask: [[Category:Bioinformatics]] [[Category:Application expert]] | ?centre | ?competence }} </nowiki>
| |
| − | | |
| − | 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 altogether 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:
| |
| − | ** [[Special:Categories]]
| |
| − | ** [[Special:Properties]]
| |
| − | * '''Use singular for names.''' E.g. Application expert, Resource, Centre...
| |
| − | * '''Follow naming protocol for titles, headings and names.''' It's right [[#Titles, headings and names|here]].
| |
| − | * '''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 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 potentially 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: <nowiki>[[competence::python]], [[competence::MSA]], [[centre::NSC]]</nowiki>. In short, do not mess around with types and everything will probably work out OK.
| |
| − | * '''Except when it's ludicrous to do so.''' [[Property:Description]] is of type string, because these should be unique, should be a phrase, and would thus look silly as a page heading or link, and for other reasons that are clearly written out on its property page. A numeric property that gives the number of petaflops on a resource would likewise be silly with Type:Page. If need arises, combat need with careful consideration, and when you finally give in, choose another type and provide reasonable rationale on the Property page.
| |
| − | | |
| − | == Creating pages ==
| |
| − | ;Ensure that you have [[#Set up your watch lists and notifications|set up your watch preferences and notifications]] correctly.
| |
| − | :Watch all pages that you create. Unwatched pages rot and we do not want that.
| |
| − | ;Look at the [[:Category:Page example|Page example]]s
| |
| − | :These are in the proper layout and use all the nifty templates for getting all the required information right. Chances are that much of the tedious work has already been done for you.
| |
| − | ;Put some deep thought into the choice of page title.
| |
| − | :This is a wiki, so it matters a lot. See the relevant [[:Category:Page example|Page example]]s for more details. Read the [[#Titles, headings and names|naming policies for titles, headings and names]] so you get it right.
| |
| − | ;Create the talk page
| |
| − | :Also called the Discussion page. As this wiki is not open for unauthenticated editing other than through the talk pages, these are our primary form of input from the general public.
| |
| − | | |
| − | == Page designs and templates ==
| |
| − | Working on that now...
| |
| − | | |
| − | == Editing help ==
| |
| − | Editing help is available here: [[Help:Editing]].
| |
