Creating Content -
Guidelines and Recommendations
This page provides guidelines and suggestions for creating content (aka documentation), in our TWiki and elsewhere. For page creation guidelines and naming conventions, be sure to review the TWiki Topic Guidelines.
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
. So... don't.
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.
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.
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.
Divide and Conquer
Divide your content into recognizable sections. 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 a 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)
Plan Your Headers
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.
Break It Up
|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.)
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. firstname.lastname@example.org
See TWiki.Text Formatting Rules
or the Formatting help section at the top of any (edit) page for details.
Set off Commands
Wrap commands in &;t;verbatim> tags to make them easier to see.
Instead of this:
To take the machine out of rotation, use yinst stop akamai_status -print -cont -h b1.finance.scd
To take the machine out of rotation, use
yinst stop akamai_status -print -cont -h b1.finance.scd
TWiki's default behaviour is to automatically link anything it thinks is a WikiWord
(essentially, any word with embedded capita letters). Unfortunately, terms like MySQL, OpsDB, MediaSuite, 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.
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.
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 TWiki.
The following may prove helpful: