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