Creating Content -
Guidelines and Recommendations
This page provides guidelines and suggestions for creating content (aka documentation)
in our Wiki and elsewhere.
For page creation guidelines and naming conventions,
be sure to review the TopicGuidelines.
Don't Think About "Documentation"
A lot of people hate writing documentation.
They don't mind writing, but they can't stand the thought of Writing
Don't think too much about formatting.
Don't think about word choice or commas or spelling or grammar or Aaaaargh!
Don't think. Just type.
Get the thoughts down in electrons.
We'll make it all pretty later.
When you are ready to think about format...
- Keep It Short and Simple
- Write Conversationally
- Think Globally
- Divide and Conquer
- Break it Up
- Highlight Key Words
- Set off Commands
- Choose Good Role Models
- Request a Review
- Learn More
Keep It Short and Simple
Many people find it more difficult to read text online than on paper.
Also, people reading web pages tend to skim more.
Keep their attention.
Use short sentences. They're easier to read.
One subject, one verb, one idea.
Rule of Thumb: No more than 10 words in one sentence.
Keep paragraphs short too.
It's easier to read several short paragraphs than one large paragraph,
especially on screen. Stick with two to four sentences if possible.
Don't go crazy over this; just hit return twice every now and then.
Rule of Thumb: No more than 4 sentences in one paragraph.
Write the way you would talk.
You understand the subject;
how would you tell a co-worker about it?
Keep the style clear and expressive. Avoid jargon.
Your readers may not share your background.
Many readers (or writers) are not native users of English.
Think about the reader as you write.
Avoid slang terms and inside jokes.
Use punctuation; it provides landmarks to the reader.
Divide and Conquer
Divide your content into recognizable sections.
If you have several large sections,
consider putting them into separate Topics (pages),
then create a "main" top-level page that links to the various parts.
If there are multiple ways a reader might come to your content,
consider putting content in separate pages (for individual section viewing),
appropriate sections into other "high-level" documents.
for details on Wiki's
Make a list
If there are more than 3 items in a list, make a list.
In the Wiki, bullet lists are formatted as: 3 spaces, asterisk, 1 space, text.
For deeper levels, prefix with another set of 3 spaces.
* level 1
* another line
* level 2
* level 3
* back to level 2
For an ordered (numbered) list, substitue
1. level 1
1. another line
1. level 2
1. level 3
1. back to level 2
- level 1
- another line
- level 2
- level 3
- back to level 2
Not only do these draw the eye, they show up in the table of contents.
A page should always have a level one header (
) at the top (as the page title).
After that, it's your choice whether to use additional level one headers or not.
However, please try not to skip levels;
please don't jump from
---++ (Level Two)
---++++ (Level Four)
Use short, meaningful, headings.
The header should tell the reader, briefly, what the section is about.
Don't include clickable links in headers.
Put links in the body text.
Highlight Key Words
to mark important words and make them catch the reader's eye.
to mark things that would be typed.
When including an email address, don't abbreviate.
is clickable. bob@ is not.
or the Formatting help section
at the top of any (edit) page for details.
Set off Commands
Wrap commands in <verbatim> tags to make them easier to see.
$ ls -al /bin
Instead of this:
To take the machine out of rotation, use stop akamai_status -print -cont -h b1.finance
To take the machine out of rotation, use
stop akamai_status -print -cont -h b1.finance
The Wiki's default behaviour is to automatically link anything it thinks is a WikiWord
(essentially, any word with embedded capita letters). Unfortunately, terms like MySQL, FreeBSD, and others all look like WikiWords.
Take control of your content, putting links where you
want them to be,
by wrapping the body text in <noautolink> tags:
---+ Page Title
Specify links by wrapping them in double brackets:
See What are all those little question marks ?
for additional details.
Most writing style guides recommend that you spell out what an acronym stands for
in the first reference on a page, followed by the acronym itself in parenthesis.
For any additional references on the same page, you can simply use the acronym.
You can bend this rule if the acronym is so common in your industry,
or so well understood by your particular audience,
that spelling it out is unnecessary or detracts from the text.
(Examples: SMTP, MySQL, BSD, IM).
Link to Deeper Details
Take advantage of links to provide references to further reading.
If a topic is discussed in greater detail elsewhere,
provide a link when you first mention that topic.
The knowledgeable reader can choose not to click;
readers interested in additional detail can choose to explore at their leisure.
In any case, you won't need to clutter your page with extra explanations.
Wikipedia is a great resource for defining technical terms, etc.
If you're stuck or confused, ask for help.
Find a similar topic and read what someone else wrote.
Talk to a co-worker.
Take a break. Take a walk.
Let your mind familiarize itself with what you want to say.
Work on something else for a while.
Request a Review
Ask a co-worker or your local technical writer to review your page.
Be sure to make it clear how much of a review you want.
Are you looking for pointers? Technical comments? A rewrite?
Keep an open mind.
Learn from the feedback you receive.
And, if you disagree with a reviewer's comments, ask someone else!
Choose Good Role Models
Imitation is the sincerest form of flattery.
Take a peek inside pages you like
(use the "View Raw Text" link at the bottom of the page).
How are they constructed?
Read what others write.
When you see something you like, make a note of it.
Save boilerplate paragraphs for re-use. Share tips.
You may never consider yourself to be A Writer
but you should find that writing gets easier with practice.
Just keep putting words on paper or screen.
After a while, you may even discover that you enjoy it.
Joel on Software (excerpt below)
Break things down to short sentences.
If you're having trouble writing a sentence clearly,
break it into two or three shorter sentences.
Avoid walls of text: entire pages with just text.
People get scared and don't read them.
When was the last time you noticed a popular magazine
or newspaper with entire pages of text?
Magazines will go so far as to take a quote from the article and print it,
in the middle of the page, in a giant font,
just to avoid the appearance of a full page of text.
Use numbered or bulleted lists, pictures, charts, tables,
and lots of whitespace so that the reading "looks" fluffier.
"Magazines will go so far as to take a quote from the article and print it,
in the middle of the page, in a giant font,
just to avoid the appearance of a full page of text."
(from Joel Spolsky;
Painless Functional Specifications - Part 4
, Rule 3. He said it better than I could. - V.)
Books, Articles, and Links
There are many books and articles that provide writing tips. 11 Ways to Improve Your Writing and Your Business
, from The Roberts Group, is especially good.
It concentrates specifically on business writing -
the kind of writing you do when you create a page on this Wiki.
The following may prove helpful: