DocGuidlines

up

Documentation Guidelines for Writing Mactel Wikis

Preface: The guidelines contain a lot of DOs and DONTs. Take them as recommendations. All wikis for running Ubuntu on a Macintosh reside in the user community pages and everybody is free to contribute to them.

The MactelSupportTeam tries to improve the overall comprehensibility of these documents.

Guidelines

  • Macintosh computers are identified by their product name, model-identification (= hardware revision), release date.

    • Example: MacBook Pro (5,1), release date: early 2008

  • Each hardware revision of a Mac gets a separate wiki for each Ubuntu version.

  • Naming convention:
    Each hardware revision of a Mac gets a hardware revision page, that links to the wikis of available Ubuntu versions.
    Example:
    help.ubuntu.com/community/MacBook4-1/
    The URL should not contain special characters like comma, dot, whitespace, etc...

    The product name in the title/URL is constructed by:
    - omitting the space, if the right-hand word starts with a capital letter (MacBook Air -> MacBookAir)
    - replacing the space with underscore, if the right-hand word starts with a lowercase letter (Mac mini -> Mac_mini)

    To keep the URL at minimum length, the second part of the Ubuntu version is omitted (Intrepid Ibex) -> Intrepid)

  • The URL's (Model start pages)

  • Things that are common to all Mactel installations go here: Apple Intel Installation

  • Don't link to sibling wikis. Use the link in the template that leads to the Mactel CommunityHelpPages, or the up-link to the hardware revision page.

  • Use the documentation template from here: Creating a new page

  • Mind the spelling of component names: It's "Mac Pro", but "Mac mini".
  • Write the wiki for everybody, not just for computer experts. Use marketing names where possible. Explain in detail every step it needs to achieve something and introduce abbreviations that are not commonly known.
  • Warn people if you think they might run into problems somewhere.
  • Test everything you write as thoroughly as possible.

  • Make the wiki look nice. Smile :)

IconUsers.png
The MactelSupportTeam is about to restructure and reorganize the documentation for Intel-based Macs. If you are interested in helping, please visit our team page for information. For all Mactel wikis, there is a starting place here. There is also a thread about planning the Mactel documentation going on.



MactelSupportTeam/DocGuidlines (last edited 2009-12-09 07:44:20 by g226034004)