Article Writing Guidelines

The objective of an article is to provide a high-level overview about a specific topic. It should answer questions related to what it is, and tightly-related details that provide more information.

Word Count

Use no less than 1500 words and no more than 3000 words for an article. Consider splitting a topic into more than one article if more than 3000 words are required. If an article is too short, consolidate related topics into a new article, or include other tightly-related information to reach 1500 words.

Writing Instructions

An article contains three sections: an intro, a body, and a concluding statement.

The objective of the intro is to provide a succinct summary of the topic, outline the document that follows, and convince the reader to continue to read.

The body is the main content that informs the reader about the main topic of the document, and should be as tightly related as possible.

The concluding statement should be a paragraph that summarizes the article, and perhaps direct the reader to other related content.

Intro

Keep the intro to between 6 and 10 sentences, broken down into 2 or 3 paragraphs. The first paragraph should be a quick 2 to 3 sentence summary of the topic, or some background to the topic, such as a problem statement. The remaining portion of the intro will begin to lead more into the topic itself, discuss what to expect by reading further, and to convince the reader to continue.

Body

Follow the general Documentation Guidelines for how to break up an article into sub-headings. Keep the content of each to between 250 and 300 words. Break up a sub-heading into a second one, or child sub-headings if it begins to exceed 300 words.

Keep on topic. Help to answer questions about what the subject is, rather than how to use it. However, include tutorial-style information where applicable, but as sparingly and succinctly as possible. Give a very light summary in the shortest space possible, and refer to related tutorials for more details and instructions. Write a new tutorial if none is available and the topic is of great enough importance.

Conclusion

Close the article with one paragraph. Provide a review of what the reader has just read through, and summarize the topic in general again. Optionally, provide links to further reading or another call to action.