Help:Howto

Revision as of 14:50, 27 September 2013 by Tierlieb (talk | contribs) (Namespace)
Writing for OXpedia

Summary: This article explains how to write a great OXpedia article.

First and foremost: A wiki thrives on articles. If you only follow one rule, then it should be this:

"Write the article you are thinking about the way you want to." 

Then let us know. If it needs fixing in anyway then we will fix it for you. On the other hand, if you prefer to write the best article possible, then this style guide is meant to help you.


Style Guide

Writing

There are tons of articles on writing technical documentation (see below for links). 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. This is obvious for UI articles. But for server articles, it is not that clear-cut, as the backend is usually backwards-compatible with OX6. When in doubt, put it in the main namespace (that is the one without any prefix).

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 {{Version|7.x.x}} and 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 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.

Who we are

We are the OXpedia team. You can reach us via oxpedia@open-xchange.com