back to CATS home

Knowledge Base

General Tips

Introductory Material

Good articles start by briefly introducing the topic. We discuss lead sections in greater detail below. As the lead section always comes above the first header, it is almost never useful to put an ==Introduction== or something like that. Sometimes, the section right after the lead is a general description of the topic, and is called "Overview." However, more specific section titles and structures are generally preferred.

Paragraphs

Paragraphs should be relatively short, but not so short that they seem incomplete. A long paragraph can normally be split into two or more separate ones with similar themes, as long as the second paragraph gets an introductory sentence to keep the reader on-track, even one as brief as "Other examples abound."

Conversely, a one-sentence paragraph is like a cannon-shot during a performance: it attracts so much attention that it had better be good. An entire article that consists of one-sentence paragraphs can normally be consolidated thematically into a few paragraphs.

Paragraphs might be replaced with tables or lists, but this should only be done when it is the best option for displaying the information. Unnecessary lists are especially disruptive to the flow of the article.

Use Headings

Headings help clarify articles and create a structure you can show in the “Table of Contents.”

Headers are hierarchical, so you should start with level 2 headers (==Header==) and follow with lower levels: ===Subheader===, ====Subsubheader====, and so forth. Whether extensive subtopics should be kept on one page or moved to individual pages is a matter of personal judgment. If the rest of the community adds more information later, it may be necessary to move a subtopic to another page.

Insert Images

If the article can be illustrated with pictures, find an appropriate place to position these images where they relate closely to text they illustrate. If there could be doubt, draw attention to the image in the text.

Using Hyperlinks

At some point an article will refer to a topic covered in another knowledge base article. Rather than repeat the information, link to it. Link to external web sites at the bottom of the article.

Add Corrections and Updates

If you spot inaccurate or obsolete information, please edit that knowledge base page. Follow wiki etiquette guidelines when you edit someone else's work. Alternatively, you can send corrections to cats@cdl.edu (please refer to the URL of the document needing revision).

You must be logged in to save your changes.

Login