Wikibooks:WikiProject Macintosh/Guidelines

Tone

Mac books are written for users with little to moderate computer experience, probably at home or on the client side of a large network. Therefore, Mac books should aim to be very light and relaxed. The way language is used should make reading a Mac book a fun activity in itself. Jokes should be subtle and not over-used. And above all, nothing should be done at the expense of clarity. A reader should be able to absorb everything with one read-through of the book. Repeat key concepts from section to section (in parentheses, perhaps) as a reminder.

Lingusitic Conventions

For the sake of consistency, follow these linguistic conventions:

• Use American spelling in all Mac WikiBooks.
• Use the serial comma.
• Avoid using elipses (...) to end sentences.

Structure

The organizational "tree" of a Mac WikiBook looks like this:

• Main Page
  • Parts (optional)
    • Chapters, Appendices, and Glossaries
      • Sub-Chapters (optional)

Nest each one inside the one "bigger" than it.

A Word on Parts

Parts are used only in books covering suites of Applications. Instead of linking to chapters on the main page, these books link to parts. Each part is like a book in itself, containing an introduction and a table of contents linking to the part's own chapters and appendices.

A perfect example of a book that uses "parts" is the iLife book. Each application gets its own part, and therefore its own table of contents and glossary. This vastly simplifies getting around the iLife book.

A Word on Sub-Chapters

Sub-chapters complexify things. Avoid using them if possible, but put them in if a chapter becomes huge and unwieldy on one page (such as a chapter that explains every single application in Mac OS X Tiger). Please do not put sub-chapters inside sub-chapters.

Main Page

Each WikiBook's must have a main page. This starts off with an Introduction section. The Introduction has, in this order:

1. A section about the product(s) described in the WikiBook
2. A section about the WikiBook itself, exlpaining what one is for new users and what the WikiBook does and does not cover

   * Include the obligatory "assumes knowledge of Mac OS X Tiger message".

3. A section about how to use the WikiBook

   *Nesting of Menu commands and files (copy verbatim from another WikiBook, if you'd like)

   *Clarification of confusingly similar words (e.g. windows vs. Windows) and interchangable words (e.g. application and program)

   *Explanation of each kind of Info Box or other special template used in the WikiBook.

The second section of the Main Page must is the table of contents, with links to all chapters, appendices, and glossaries. Coding tables of contents can be confusing. Follow this format exactly:

# [[Chapter 1]] {{stage short}}
#: Chapter 1 description
# [[Chapter 2]] {{stage short}}
#: Chapter 2 description
# [[Chapter 3]] {{stage short}}
#: Chapter 3 description
# Appendices
#:* [[Appendix A]] {{stage short}}
#:*: Appendix A description
#:* [[Appendix B]] {{stage short}}
#:*: Appendix B description 
# [[Glossary]] {{stage short}}
#: Glossary description

For an example of a perfect table of contents, see the Mac OS X Tiger WikiBook.

No Advertising!

It's legitimate and helpful to mention an application (Freeware, Shareware, Open Source, or Regular), brand of hardware, or website, but this wikibook shouldn't be a platform for advertising, nor should any tutorial contained in it ever rely on a non-Apple product.

Book, Not Encyclopedia

Remember that Mac WikiBooks are books, not encyclopedias. Keep a casual tone. This book is supposed to be the Mac OS X user's best friend, not a dry encyclopedia of information.

Images

Put in color screenshots, product images, and diagrams in important places. Use them when necessary, but never frivolously, so the pages can load over a dial-up connection. Also make sure the screenshots do not show any "haxies", themes, etc. Keep the screens uncluttered and familiar to the average user (for instance, use bundled Apple wallpaper, don't over-customize toolbars, and don't show any alternative icons). Also, when talking about a window or a menu, the screenshot should not include anything else. As a rule, full screenshots should be 830px wide.

Screenshots should be centered except when impractical, always appear as thumbnails, and be labeled in this format: "Fig. 1 - Here is a caption, which is "dry" (not funny or interesting) and does not contain instructions."

NOTE: Check our Image Directory for some great images you can use in your writing.

Tables

Tables should be used whenever appropriate.

• Table width should be set to 830px
• The border should be set to 0
• Cell Padding should be set to 3
• Cells should be either 4D804D (dark green) or B5E3B5 (light green)
• Tables should be labeled in this fashion "Table 1. This is a simple caption."

Info Boxes

Use Info Boxes whenever they make sense. Use the following templates:

{{Mac Warning Box|Put Warning text here.}}

{{Mac Note Box|Put Note Text here.}}

{{Mac Trick Box|Put Trick Text here.}}

{{Mac Background Box|Put Background Text here.}}

WikiProject Templates

These templates should be used to display affiliation with the Macintosh WikiProject.

• Template:WP Mac Module - Use this template at the top of all module's talk pages.
• Template:WP Mac Cleanup - Place this template at the top of all bad modules and their talk pages.