Help:Howto

From Open-Xchange
Revision as of 12:35, 28 August 2014 by Tierlieb (talk | contribs) (→‎Templates: better example values)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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}} - can also use several versions, separated by space, dash and space.
  • The version, used for pages with information that becomes valid for a specific version: {{VersionFrom|7.4.0}}
  • The version, used for pages with information for works only for a range of versions: {{VersionFromTo|7.4.0 - 7.4.2}}
  • The version, used for pages with information for works until a specific version: {{VersionTo|7.4.2}}

Author information

  • Every user should feel free to improve any wiki article
  • The person primarily responsible for the article is its author
  • The author of an article should be identifiable by editing a page and looking at the top
  • Mark yourself as the author of a page by putting in a commented section (invisible when not editing) at the top of a page like this:
<!-- Author: Karsten Will <karsten.will@open-xchange.com> -->

Linking to headers and page sections

You may have noticed that Mediawiki automatically creates IDs for every page heading. The table of contents uses that so you can jump to the relevant section. The problem is that the ID is based on the title of that section. Which tends to get changed. We recommend not to use those IDs as anchors, as this is prone to breaking when the title is changed (remember the "cool URIs don't change" message from the W3C a decade ago? This is similar). Instead, go the extra mile and create your own anchor. How do you do this? With a #template of course! Simple put {{a|my_anchor}} in your article.

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.

Exceptions

Because we do a lot of code descriptions, we tuned that part of MediaWiki. Probably beyond all recognition. So here are some details:

  • <code> does nothing unless you feed it with language information, then it does code-highlighting
  • <nowiki> stops other markup from being recognised
  • <tt> does fixed width characters
  • <pre> does fixed width characters and honours whitespaces

Who we are

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

Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=Help:Howto&oldid=18354"