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

Guidelines

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
  • Practice
  • 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 Conversationally

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.

Think Globally

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), then INCLUDE appropriate sections into other "high-level" documents. (See WikiTutInclude for details on Wiki's INCLUDE functionality.)

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

  • level 1
  • another line
    • level 2
      • level 3
    • back to level 2


For an ordered (numbered) list, substitue 1. for the *.

   1. level 1
   1. another line
      1. level 2
         1. level 3
      1. back to level 2

  1. level 1
  2. another line
    1. level 2
      1. level 3
    2. back to level 2

Use Headers

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) directly to ---++++ (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

Use bold or italic to mark important words and make them catch the reader's eye. Use fixed-width to mark things that would be typed. When including an email address, don't abbreviate. bob@ycompanyfoo.com is clickable. bob@ is not.

See TextFormattingRules 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.

  <verbatim>
     $ ls -al /bin
  </verbatim>

Example:

Instead of this:
To take the machine out of rotation, use stop akamai_status -print -cont -h b1.finance

Try this:
To take the machine out of rotation, use
   stop akamai_status -print -cont -h b1.finance 

Use <noautolink>

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:

  <noautolink>
  ---+ Page Title
  
  Text...
  </noautolink>

Specify links by wrapping them in double brackets: [[LinkedWikiWord]]. See What are all those little question marks ? for additional details.

Define Acronyms

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

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.

Hint: Wikipedia is a great resource for defining technical terms, etc.

Recommendations

Don't Stress

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.

Practice

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.

Additional References

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

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:

Topic revision: r7 - 17 Apr 2012, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback