Help:Howto
Summary: This article explains how to write the best article possible
First and foremost: A wiki thrives on articles. If you only need one rule, then it is this: Write the article you are thinking about the way you want. Then let us know. We'll fix it. If you prefer to write the best article possible, this style guide is meant to help you do so.
Style Guide
Writing
There are tons of articles on writing technical documentation. Here is a condensed version:
- If you have got the choice between funny, eloquent and concise, go for the latter. (Actually, don't "go for the latter", but "go for concise", as the next guideline will explain).
- Make sentences that stand on their own. This is especially important in a wiki where paragraphs or even lines might be moved around.
Namespace
AppSuite-specific articles go into the AppSuite:* namespace. That means you simply prefix the page title with AppSuite:, that's all. The tricky part is knowing whether the article is AppSuite-specific. It is obvious for UI articles. But for server articles, it is not that clear-cut, as the backend is usually backwars-compatible with OX6. When in doubt, but it in the main namespace.
Layout
Due to some php magic, our skin does not show the article title. The benefit is that you are not bound by the restrictions of article titles on MediaWiki. To put up a <div class="title">Title of the article</div> element on top.
Decide whether to use the table of contents, which links all article headings and subheadings. If you do so, use __TOC__. Use it after the intro sentence and before the first heading that you wrote.
Write an intro sentence that gives the user a rough overview of what the article covers.
Categories
You are free to invent new categories. The following ones are just a fraction of all categories this wiki contains, but they are those we would like to see used more widely. We propagate these by linking them from the main page so they get a lot of visibility. If you want your hard work to be found, use them:
- This wiki contains articles for OX5, OX6 and AppSuite. Please indicate which version you're referring to by adding either [[Category: OX5]], [[Category: OX6]] or [[Category: AppSuite]].
- Server-related articles usually concern both OX6 and AppSuite, so simply use both categories.
- Articles here aim at a certain target group. Ask yourself whether you are writing for :
- Potential customers, [[Category: Customer]], people interested in buying the product
- Users, [[Category: User]], people working with the product
- If you are writing for users, more power to you, but consider letting the people responsible for the user manual know. Users get translated manuals, so these articles leave the wiki after an incubation period.
- Admins, [[Category: Admin]], people running the product on their servers
- Developers [[Category: Developer]], people extending the product using our SPIs or APIs
- Go into detail, explaining whether you are writing about a server component [[Category: Server]] or a user interface component [[Category: UI]]
Numbering and versioning
As opposed to normal wikis, it is not just the current version of an article that interests a user: Documentation for an older version of the product might be needed, too. The way we handle this might seem familiar to linux users:
- When starting an article, use a good title. No numbers needed. For example "My useful article"
- Once you realize that you are creating text that needs to be versioned, create a page for that version by adding a space and then the version number. For example: "My useful article 7.4.0". Ignore the fact that we used both "v7.4.0" and "7_4_0" in the past. That's outdated.
- This article is probably a verbatim copy of the one you worked on last. That should not be much trouble. If you're admin, you can even move the article. That takes care of the next step, too, which you have to do by hand otherwise.
- Replace the content of the old article with a redirect to the most current version. For example: "My useful article" contains only #REDIRECT [[My useful article 7.4.0]]
- When you have articles for more than one version, please use the Template {{versioned}} to point to the next and previous version in line.
Templates
Templates make recurring tasks easier. The following templates are used regularly within the OXpedia:
- The [[[API status|level of stability]] a described feature has: {{Stability-unstable}}, {{Stability-stable}}, {{Stability-frozen}} and {{Stability-deprecated}}
- The version, used for pages with information for a specific version: {{Version|7.4.0}}
Hints for Mediawiki
This is a media wiki... even if our great design is trying to fool you into thinking otherwise. So all Mediawiki[1] tricks apply here, too.
- Editing basic for Wikipedia
- Markup cheat sheet (PDF)
- Mediawiki help pages
- Wikipedia's guide to layout
Who we are
We are the OXpedia team. You can reach us via oxpedia@open-xchange.com