Apple Mac OS X Server v10.6 - Manual (Page 79)

Chapter 10 Improving Internal Documentation 79
Page Type Tags Description
Table of contents contents, documentname,
categoryname If you have a long, multipage
internal document in wiki
format, it’s useful to have a table
of contents page that is linked
to from a category page. This
page has links to all content
pages for the document.
Content documentname, categoryname Includes wiki-formatted internal
documentation content. This
is linked to from the table of
contents page.
Single-page documents documentname, categoryname If a document is short, create a
single page with its content and
link to it from a category page.
Choosing Which Documents to Convert to Wiki Format
Sometimes documents are best left in PDF format and not converted to wiki pages.
For example, if the document is infrequently used or updated, it might not be worth
the effort to convert it. You can attach these documents to wiki pages, which allows
people to more easily find the most recent version of the document.
Here’s a comparison of PDFs and wiki:
Wiki PDF
Dynamic Static
Easy to update Hard to update
Easy to link to from other wiki pages Hard to link to from other PDFs
Can print single wiki pages Can print entire PDFs
Must give people wiki access to view the wiki
pages Can distribute without giving people wiki access
Reducing the Need for Single Ownership
Typically, an internal document is written by a single person but is read and used by
many people. The writer of the document usually has a primary responsibility that isn’t
writing documentation, so the internal document usually takes lower priority and can
easily become outdated.
By allowing everyone to edit the documentation or comment on possible issues, the
documentation can stay up to date even if the original writer is too busy to work on it.