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)
  

  • help.ubuntu.com/community/MacBook
    help.ubuntu.com/community/MacBookPro
    help.ubuntu.com/community/MacBookAir
    help.ubuntu.com/community/Mac_mini
    help.ubuntu.com/community/iMac
    help.ubuntu.com/community/MacPro
    help.ubuntu.com/community/xServe
    link to the hardware revision pages wiki.

    The links get updated by the MactelSupportTeam, after a new hardware revision of a Mac product has been released.

• 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.