The aim of a preferred article style on the SDIY wiki is to help editors produce articles with consistent, clear, and precise language, layout, and formatting. The goal is to make reading the wiki easier and more intuitive to use. Consistency in language, style, and formatting promotes clarity and cohesion. Writing should be clear and concise. Plain English works best: avoid ambiguity, jargon, and vague or unnecessarily complex wording.
Structure of the article
Good articles start with a brief lead section introducing the topic. The lead section should come above the first header. Include the article title in bold within the first sentence or so, to define it.
Create new useful information. If there is already something relevant out there, eg. on Wikipedia, instead of duplicating the same information, just link to the external source.
Articles should be kept relatively short. Say what needs saying, but do not overdo it. Articles should aim to be less than 30 KB worth of prose. When articles grow past this amount of readable text, they can be broken up into smaller articles to improve readability and ease of editing. The headed sub-section should be retained, with a concise version of what has been removed under an italicized link to the new article. Each article on a subtopic should be written as its own stand-alone article. Avoid creating pages with large amounts of unbroken text, break it down into easily digestible sections, this makes it easier for the reader. Don't create multiple small linked articles when they can all go just as well on one page under separate headings.
Paragraphs should be short enough to be readable, but long enough to develop an idea. To increase readability, overly long paragraphs should be split up. One-sentence paragraphs are unusually emphatic, and should be used sparingly.
Style and tone
Assume readers are reading the article to learn. It is possible that the reader knows nothing about the subject, the article needs to explain the subject fully. Articles, and other content, should be written in clear English to be clear and understandable. Don't use jargon unless linking to an article explaining the meaning. In the same sentence, expand on facts that may not be obvious to to the reader.
Most engineering and other technical reports are written in the passive voice as a matter of convention. Articles should be written from a neutral point of view leaving the reader to make their own mind up. Don't use peacock or weasel words, these are words that add opinion without really backing it up. Words/phrases such as "an important", "one of the best", "the most influential", "is widely regarded as", "is widely considered", "it has been suggested", "is widely regarded as", "it has been said that", etc. If you do include statements like these, provide a reference to verify why this is the case.
Articles should use only necessary words. This doesn't requires that the writer make all sentences short, or that avoids all detail and treats the subject only in outline. Reduce sentences to the essentials. Wordiness does not add credibility to articles. The most readable articles contain no irrelevant information. While writing an article, if you find yourself digressing into a side subject, consider placing the additional information into a different article. Then provide a link to the other article, so that readers who are interested in the side topic have the option of digging into it, but readers who are not interested will not be distracted by it.
Write material that is true, check your facts. Provide sources that can be used to verify your facts. This is a crucial part of citing good sources. Even if you think you know something, you have to provide references anyway to prove to the reader that the fact is true. Sometimes information that seems reliable, turns out to be incorrect when checked against a valid source.
Try to use reliable primary or published sources, and not only rely on online resources. Providing good sources is also useful for readers, to find where to look for more in depth information.
Always provide a list of verifiable references for what you write, under a level 2 heading called "References", at the end of the article.
- Ten Guidelines For Standards Engineers by F.S. Stein, JEDEC, 2002
- Guide for the Use of the International System of Units (SI) by Ambler Thompson and Barry N. Taylor, NIST, 2008