How to contribute documentation
- Content formatting
- Creating new pages
- Page versioning
- Page tagging
- Credits and ownership
- Good reading
Midgard documentation is maintained as a Wiki editable by all registered site users. If you'd like to contribute content to the wiki, contact Henri Bergius to get editing permissions. The documentation area is powered by the Midgard Wiki component.
Content formatting
Editing is done using the Markdown syntax, which should be relatively natural to most users:
## Second level header
Paragraph of text, _some emphasis_
* List item one
* List item two
1. Numbered
2. List
<?php /* some example code */ ?>
> Quote from some person
Markdown also passes regular HTML through, so you can use HTML for tables and similar things. However, using HTML should be limited to the places where it is absolutely required.
Please also observe the Midgard wiki formatting conventions when contributing material.
Creating new pages
Creating new wiki pages is easy, simply type the name of the page into your content, and surround it with square brackets: [Some page]
If you want to use different label for the link than the actual target wiki page name, use the following format: [Some page|link text]
Screenshots can be included into content pages by uploading them to an org.routamc.photostream folder (preferably, this one) and then using the following format: [photo: GUID]. The correct GUID is shown in the image's display page in the gallery.
There is also more information about linking formats supported by the Midgard wiki.
Please note that the wiki structure is flat, so use unique names (name-spaced if needed) for your pages.
It is also good to be atomic. So instead of making one wiki page about How to write MidCOM components, split it into different parts about MidCOM component namespacing, MidCOM component interface class, etc, and the create the central page to collect those links.
Page versioning
All documents are versioned using MidCOM's revision control system, and can be browsed and managed using its user interface.
Page tagging
Read the Tagging in Midgard Wiki document.
Credits and ownership
Once you have contributed some documentation to the wiki, remember to add yourself to the Authors page.
Please note that all content on the Midgard wiki must be made available under same licensing terms as the Midgard website in general, the Creative Commons Attribution-ShareAlike license. This makes the whole wiki Open content.
Good reading
- Markdown basics and the syntax documentation
- Wikipedia introduction to content contributing
- Midgard wiki formatting conventions
- Midgard wiki linking formats