semantic-mediawiki.org:Documentation guidelines
From semantic-mediawiki.org
This page summarises some guidelines for creating content on this site.
Contents |
Help pages, SMWToc, and documentation
The primary documentation pages use Template:SMW user TOC which puts them in 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). There are additional pages in the Help namespace that aren't in this main table of contents.
There are additional pages outside the Help namespace that are "documentation". All such pages must be in Category:Semantic MediaWiki documentation or a subcategory (or, for other languages, in a translated version of those categories).
- There is a Property page for every special property with documentation, all are in the subcategory Category:Special property.
- The documentation uses a limited set of sample pages on s-mw.org 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 risky and those pages on semanticweb.org should be categorized with [[Category:Pages referenced from SMW help]]
- A few concepts have pages in the main namespace, such as Property. Maybe they should move to the Help: namespace?
History
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 semantic-mediawiki.org so much.
Translation and Versioning Overview
The basic method 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:Docu: 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 allpages 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.
Usage Guidelines
Both Template:Language and Template:Docu 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 Documentation guidelines (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 (de)". We might hack our local MediaWiki to hide those suffixes when displaying a page.
Versioning
Using Template:docu, we can now keep documentation for many pages in parallel. This changes the way in which docu 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 "Help:Inline queries" and "Help:Inline queries 0.7". When SMW 1.1 would introduce new changes, we would just move "Help:Inline queries" to "Help:Inline queries 1.0" and create a new page "Help: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 tempalte 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 docu.
Hence the page without version is always the most current docu. This also means that documentation pages should avoid Magic Words like p: they would change their meaning when moving the page. It is probably still 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 docu.
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.
Help: and Main: namespaces
Currently, the namespace Help: is used for all documentation pages that are relevant to users of SMW and not just to semantic-mediawiki.org or to the SMW Project. The idea is that one could export the pages in Help: and distribute them to other wikis as a local copy of the handbook. Most pages are currently in Help: and some that are not maybe should go there too. In the future, we might also have pages with tutorials ("How to create an internationalised wiki with SMW" or "How to run SMW on a mobile phone"), or with typical example wikis ("DiscourseDB", "ontoworld.org" or "korrekt.org") that users can look at to see how certain applications can be realised. Such pages would probably not go into Help:
We probably should have custom "Help:" namespaces for other languages, but these are not setup yet. In any case, just moving the pages over in the future will be no extra work (even if one of the moved pages is the "master page" for some set of pages, the redirect is resolved in all SMW queries).
