semantic-mediawiki.org:Documentation guidelines

This page summarises some guidelines for contributing to the documentation on this site.

Goal

The SMW project strives to ensure a maximum quality and reliability of its handbook. For this reason, some essential pages on this site can only be edited by users in the group contributors (to become a contributor, please send an email to Markus Krötzsch). There are many other documentation pages on this site that are not part of this handbook, and which are maintained independently by all users of this site. The handbook is special since it should always be up-to-date with the most recent stable release of the software, and since it has an overall structure: it is not just a set of pages but more like a traditional manual with each page forming a chapter.

Many other documentation pages, such as tutorials or example applications, are not part of the handbook, and can be edited by everybody.

If you are a contributor, please create a brief user page with your real name and some reference to your homepage or affiliation. Feel free to improve the handbook pages where needed, but do discuss major changes with the SMW developers first. Make sure that the handbook is not cluttered with information that is not really "core": instructive examples are suitable, but detailed tutorials or workarounds for bugs are not (instead, report the bug and give the workaround in the report; use [[mediazilla:1234|Bug 1234]] to link to a bug from the handbook). Keeping non-core information on separate pages is also important to allow other users to edit these parts without needing special permissions.

Documentation structure and table of contents

The SMW documentation is split into three main parts: user documentation, administrator documentation, and developer documentation. The first of those explains SMW features that are relevant to users who access the wiki via a browser. The second part is for administrators who install and maintain wiki sites. The third part is for developers who wish to contribute to SMW, or to write extensions for it.

The user documentation pages use Template:SMW user TOC which inserts a table of contents, and categorises them in Category:Semantic MediaWiki documentation. Other languages should use similar (translated) templates and category names (see details on translation below). Note that not all pages in the Help namespace are in this main table of contents. Similarly, the administrator documentation uses Template:SMW admin TOC. The developer documentation currently does not have a dedicated table of contents.

Which namespaces to use

The Help: namespace

Currently, the namespace Help: is used for essential, handbook-like documentation pages that are not editable by all users. The namespace is primarily used for documenting SMW, but it can also be used for other extensions if they find that completely public editing of their handbooks is not viable any more (typically this is the case when a handbook spans many pages but does not have a sufficiently large editor community yet to correct errors that are inserted by casual users).

All other pages, including tutorials (e.g. "How to create an internationalised wiki with SMW" or "How to run SMW on a mobile phone"), practical hints, or descriptions of example wikis (e.g. "DiscourseDB", "semanticweb.org", "korrekt.org"), should not go into the Help: namespace. They can simply be kept in the main namespace. In particular, there can be helpful documentation pages outside the Help namespace.

One could have custom "Help:" namespaces for other languages, but these are not set up so far. Hence, translations should also use the Help: namespace.

The Print: namespace

The purpose of the Print namespace is to create article collections from parts of the documentation. The main difference of this namespace is that it does not evaluate semantic annotations, so it can safely duplicate contents from other pages without obtaining their semantic data.

Other special namespaces

There are additional pages outside the Help: namespace that are "core documentation". All such pages should be in Category:Semantic MediaWiki documentation or a subcategory (or, for other languages, in a translated version of these categories).

• Datatypes of SMW are described on their respective pages in the Type: namespace.
• Built-in properties ("special properties") of SMW are described on the respective pages in the Property: namespace, and additionally categorised in Category:Special property.
• The documentation uses a limited set of sample pages on this site to show Semantic MediaWiki in operation, focused on cities and a few properties (population, area, coordinates). All sample pages must be in the subcategory Category:Sample pages. The documentation refers to ow: pages for more complicated examples; this is somewhat risky and requires regular checking to ensure that the example is still intact.
• A few concepts have pages in the main namespace, such as Property. Maybe they should move to the Help: namespace?

Translation and versioning of documentation

Documentation pages on this site refer to different languages and software versions. The basic method to maintain this is that all pages can be tagged with a language code, and possibly with a range of versions that they apply to. This is done by means of two templates:

• Template:Docinfo: denotes language and SMW version range; used for technical docu

• Template:Language: denotes language only; used for all other pages (e.g. news items)

Both templates work in the obvious way: you specify a page's language, minimal version, and maximal version via template parameters. But how are the Spanish and the English version of the same topic linked together? For this purpose, each template takes a parameter "master page". The idea is that there is one "main" page for each topic, and that all pages in other languages and for other versions that refer to the same topic then relate to that main page. Then it is easy to find a list of all pages that relate to the same topic but have another version or language.

Note how this is different from MedaWiki's interlanguage links: instead of linking to all other language versions from all involved pages, you just link to one such page. If someone adds a Spanish translation for something, then the link appears on the English and German page without those pages being changed at all.

Template usage guidelines

Both Template:Language and Template:Docinfo are briefly documented on their respective pages. The templates should normally go to the bottom of a page, unless the page is for an older SMW-version -- then Template:Docu goes to the top. Both templates contain translations for various languages, which is simply achieved by using "#switch:" statements. To add a new language, one adds a new case for each of the #switchs in the templates. One could of course also use different templates in different languages, but having only one helps to keep all languages in synch when something changes.

Basically all content pages should use one of the two templates, so that at least the language is specified for each page. If a page has no translation in the wiki yet, then it should use itself as "master page". One should normally type out the name, and not use the Magic Word {{PAGENAME}} (explanation below). If someone translates that content later, then one can refer to that page (note that the master page can be in any language). Many current pages do not have the templates yet, and you can add them when making translations.

Translation

Normally, translation is done by just creating a new page and pointing it to the original "master page" with one of the aforementioned templates. Languages are always specified with lower-case language codes.

In some cases, you get into trouble when a page's name is already taken in another language. For example "MediaWiki" is probably the same in all languages. There are two possible solutions: either find a smart variant of the page title (e.g. "Semantic MediaWiki" is called "Semantic MediaWiki - Startseite" [meaning "homepage" or "entry page"] in German). The default way of creating language variants is to add " (<Language Code>)" to the title, e.g. as in "MediaWiki". We might hack our local MediaWiki to hide those suffixes when displaying a page.

Versioning

Using Template:docu, we can keep documentation for many pages in parallel. This changes the way in which documentation is done. Documentation pages no longer have to contain exceptions such as "since version 0.7 ..." or "in earlier versions of SMW ...". Intead, when some documentation needs to change in a future SMW version, the existing page will be moved to "<Current title> <Version>" and a new updated page will be created in its place. For example, there are pages "Inline queries" and "Help:Inline queries 0.7". When SMW 1.1 would introduce new changes, we would just move "Inline queries" to "Help:Inline queries 1.0" and create a new page "Inline queries" (probably by copying the old one and changing whatever needs to be changed).

If a page is valid for the most current version, then one omits the template parameter for maximal version (maxversion). When a new version for some page is created, one thus also should enter the maximal version into the old page. After these changes, all pages (for all other versions) will automatically display the cross links to the new version documentation.

Hence the page without version is always the most current documentation. This also means that documentation pages should avoid Magic Words like {{PAGENAME}} which would change their meaning when moving the page. It is sensible to move documentation only if some amount of change really happened, and to keep minor modifications inline. Note that one might have to version the table of contents with the documentation in case of major changes.

In some cases, a new SMW version might change the structure of the documentation on page level (adding new pages, splitting existing pages into multiple ones etc.) It is not a problem if some pages have no according page in earlier versions of the documentation.

History of this site

Denny imported all pages in the category ow:Category:Semantic MediaWiki from http://ontoworld.org around December 2007. Over time S Page changed the ontoworld.org pages to be soft redirects to this wiki. There are still help and documentation pages on ontoworld.org that aren't on semantic-mediawiki.org, or have not been replaced with pointers to this wiki; there are Semantic MediaWiki pages here that probably do not belong.

In April 2008 ontoworld.org became http://www.semanticweb.org, and all content was copied to the new test wiki http://sandbox.semantic-mediawiki.org. See ow:Project to rationalize content on former ontoworld.org. This doesn't affect www.semantic-mediawiki.org so much.