The Simple-Talk Author’s Style Guide
Although we like to give a great degree of latitude in the general style of writing, any Simple-Talk article should make clear at the beginning what the article will be about. It should end by summarizing the points made in the article, and the purpose of the article. It helps to provide links for further reading, particularly to content also on Simple-Talk or another of our sites. It should also give acknowledgements and credit.
You should not write an article in the passive voice. In the passive voice I’d have written ‘Articles should not be written in the passive tense’. Do not use an academic style, but instead aim at being engaging, entertaining, and considerate to the reader.
Articles should be written for as broad an audience as possible, and should not make any unnecessary demands on the prior knowledge of the reader. If the article contains original and interesting information, even experts will tolerate occasional extra words to help the lay readers.
Don’t assume the reader knows something beyond the basics at the level you write. If you write about learning to do backups,don’t assume they know what a backup is. If you write about debugging memory values with DBCC for example, don’t assume they know the different pools of memory outside of the buffer pool. Many of our readers like to learn other technologies outside their own specialism for their general understanding and education.
Be careful of mannerisms or ‘literary tics’ in your writing. Don’t write “we all know” or any variant. We don’t, or we’ve forgotten. Sentences beginning ‘Note that…’ are likely to irritate the reader. Never start a sentence with ‘Note:’ unless this really is an aside. You cannot use this device to emphasise importance of a paragraph.
When referencing objects in the interface, whether dialog boxes, windows, panes, wizards, etc., you should refer to them exactly as they appear in the interface. Otherwise, it can get quite confusing when trying to follow along in an article. The text of a button, tab or clickable widget should be referred to in single quotes (for example, press ‘OK’).
Make screenshots relevant. Don’t include a screenshot for everything, such as accessing a menu item. Reference the screenshot within the text and correlate your information with the screenshot. Don’t show a screenshot that is different from the setup you’re describing without explaining the reasons for those differences.
Please do not start sentences with “So” or “And” or “But”.
Use fewer words when you can, and keep them short. Judging the value of an article by its length is like valuing an aircraft by its’ weight.
Write out numbers as words (e.g. Twenty-five ) when these are within text when it takes fewer than four words to do so.
A paragraph cannot consist of just a list. Bullet points can only be used for lists but need to be part of the sentence in which the list is placed. If you need to have a detailed explanation of each item, write in prose as if it were a series of dictionary entries. Never introduce a numbered list unless the sequence is important.
Don’t capitalize, delimit, or add additional formatting to words (such as bold, underline or italic) for emphasis. Neither formatting nor emoticons are part of the English Language: Emphasis can, and should, be conveyed by well-constructed phrases alone.
For numbers within text, especially where they start a sentence, or are approximate, it is always best to write one, two three etc instead of 1 2 3 etc. because we know that readers make fewer mistakes when reading numbers as words. There are limits to the practicality of doing this which are a matter of judgement. However, terms like ‘a billion’ always are more intelligible than a row of noughts, and we all use terms such as ‘gigabyte’ instead of a long line of figures. However, figures are usually, but not always, better where these numbers apply to sums of money, time of day, percentages, house numerals, years, days of month, degrees of temperature, proportions, votes, scores, speeds, time of races, dimensions and serial numbers.
Don’t capitalize words merely to show their importance. When you write databases or server, for example, don’t write Databases or Server.
Be consistent with verb tense. It is confusing for the reader if you constantly switch from present to past when trying to explain.
Be very careful about the repetition of words. This is particularly difficult for the reader when they have vague meanings such as ‘environment’ , ‘solution’ or ‘scenario’
Any article should provide original insights into the topic being tackled. It is not enough to paraphrase existing material. It will have a technical review and the author must therefore take great pains to ensure technical accuracy, checking every statement made.
If an article mentions products or services, the author must make clear any association of whatever type, with the company producing the goods or services. Unless an article is focused on a particular product, the mention of a third-party tool should include the most obvious industry-leading alternatives.
The first time you use any acronym, give the full version of what the letters stand for if there is any doubt at all, and where possible, provide a link to enable the reader to find out more. Avoid using acronyms unless they are generally accepted. It is particularly irritating if it is merely a device to avoid typing.
All writing should be in international English. Limited colloquialisms are allowed where the meaning is obvious from the context.
No text more than a sentence long should be copied verbatim without permission from the original author or copyright holder. Any source that is used in the creation of an article must be attributed, with an acknowledgement at the end of the article. Anyone who provided advice or assistance could be mentioned in the acknowledgements.
When mentioning products, all vague emotive language such as ‘powerful’, ‘robust’, ‘enterprise-wide’ will be removed. If a product has a particular advantage, this must be testable, and backed up by citation.
The editorial policy of the site is to provide interesting and original technical information about the development and administration of corporate IT applications, tools and services, using Microsoft’s leading technologies and any other technologies that are of interest. It believes in the value of third-party tools and services in the provision of IT applications, whether open-source, free or commercial. We are prone to feature Red-Gate tools because these particular tools are what we do and we’re familiar with them, but we welcome the mention of other tools where they are relevant in the context of the article.