Table of Contents
Great Articles on Technical Web Sites Depend on Copy and Technical Editing
Next week, I shall be in Atlanta (GA) to attend The Experts Conference (TEC). I look forward to meeting many of my readers there along with folks like Mary-Jo Foley and redoubtable Greg Taylor of Microsoft, who I will debate about Microsoft’s attitude to on-premises customers and other topics.
During the event, I’ll be talking to potential writers for Practical365.com to explain how we bring the articles submitted by writers from original draft to published text. I first started writing for Windows NT Magazine in 1997. One of the books published based on Windows NT Magazine articles in 1998 is still available from Amazon. I have a copy of that book at home because it contains an article I wrote about Exchange 5.0.
The late 1990s was the heyday of technical magazines, and a single edition could include advertisements worth hundreds of thousands of dollars. With that kind of revenue, Windows NT Magazine could afford to invest in copy and technical editing. Articles might go through several review cycles to expand text, correct errors, and answer questions that authors had never thought about. Everyone went through the same process and the result was excellent articles by luminaries such as Paul Thurrott and Marc Russinovich in a monthly magazine that seldom failed to please. A lot of the credit for the magazine was due to the excellence of the editorial staff.
Time moves on and magazine revenues from print advertising disappeared. We now have technical web sites that fund themselves in a variety of ways, usually through some form of online advertising or sponsorship. Other things have changed too. Technology evolves much faster today, and authors no longer have months to assess a product comprehensively before they write about it.
Guidelines for Better Technical Articles
One thing that hasn’t changed are simple guidelines that every author can follow to produce better articles:
- Don’t include leading statements that aren’t backed up with evidence such as a link where readers can find more information about a topic. For instance, when stating that Teams has 300 million monthly active users, link to the source for this information (like an analyst briefing where Microsoft gave the number or an article from a reliable web site).
- Write in the active tense. For instance, “in this article, we review Exchange Online Protection” is better than “in this article, we will review Exchange Online Protection.”
- Always be clear about who the actor is when discussing some action. For example, the reader is left to guess what “it” refers to in this text: “It is important to understand that it is a partial TGT.” A better version is “It is important to understand that the ticket generated by Entra ID is a partial TGT.” The reader now knows that Entra ID is the actor.
- Avoid terms beloved by marketing like “seamless” and “super-powers.” Use plain English instead to make text more accessible to non-English readers. “Best practice” is another nebulous term that’s best avoided. Technology evolves so fast that the notion of best practice is hard to define.
- Use fewer words than more. Generally speaking, longer articles are less popular because many readers consume text on mobile devices. The maximum word count for a long-form article is now around 1,500 words where magazine articles in the past often exceeded 3,000 words.
- Don’t clutter articles up with large numbers of screen shots. IT professionals do not need text written in the style of a child’s comic book. Each screenshot should be essential to the story and add significant value to the narrative.
- Don’t bother repeating information that’s available in Microsoft documentation. Link to the documentation and use the article to discuss information that Microsoft’s writers don’t cover.
The ideal situation is where authors tell an informative story from start to finish in an article. Knowing what story to tell is often difficulty for authors, but going into that problem requires more space than available here.
Sad Standard Seen in Some Technical Web Sites
The sad thing is that many sites don’t do a very good job of editing. I read articles across a variety of technical web sites in an attempt to identify potential authors for Practical365.com and am dismayed when I see text littered with basic errors. Or articles that could reduce the number of words by 20% and still have the same value.
A recent example is an article about how to create Microsoft 365 mailboxes that describes a distribution group mailbox (no such object exists). This is probably a simple error that the editor should have picked up (if they know about Microsoft 365 or Exchange Online). The article also recommends using cmdlets from the Microsoft Online Services module to assign licenses to new user accounts. This is in spite of the fact that MSOL cmdlets that assign licenses don’t work anymore (as some are discovering to their discomfort). For the last two years, Microsoft has advised customers to upgrade license management scripts to use the Microsoft Graph PowerShell SDK. I can’t understand how the site can publish such rubbish unless they practice “light editing,” meaning that their editing consists of uploading text to the site and pressing the big “Publish” button.
Avoiding Errors in Technical Web Sites
We make mistakes when publishing Practical365.com articles too. But we do our best to avoid errors by putting submitted articles through a copy and technical editing process. Copy editing clarifies and improves text (it still amazes me when authors submit text replete with spelling and grammatical errors). Technical editing examines the text to detect errors in statements made about the technology or code examples. Editorial exists to help authors publish articles containing the best possible text. It’s possible (and happens occasionally) that errors still appear on the site. When that happens, our policy is to correct the issue as quickly as possible.
Editing can be uncomfortable for authors if they feel that the process is too intense or points out too many issues with their writing. I’ve been told by an author that our editing “removed their voice.” That’s sad, but only because their text basically needed a complete rewrite to make sense and justify publication. Just because you think your text is good enough doesn’t mean that an editor has to agree.
Come Talk to Us at TEC
If you attend TEC and are interested in writing for Practical365.com, please visit our stand and chat with Jacob Stokes or myself. We’re always looking for new talent, people who can make technology come alive through their writing. From our side of the house, we will dedicate the right editorial resources to make your writing as good as possible when publishing your articles – and that’s a promise.
Ah, the Penton days. We did have a great editorial staff and I always felt they made our articles better.
Simple reader here. I completely agree with you except for the part about screenshots, I’ve always found it’s better to have more than less. Often when it’s hard to understand a technical article (the best technical writers aren’t necessarily the best literary ones) screenshots can help a lot to understand the article better.
That’s a fair perspective. What we tell Practical365.com authors is that each screenshot must add value to the story by illuminating something that can’t be clearly described in text. The problem with screenshots is that GUIs change so often these days that a screenshot taken last year is probably different (and can therefore confuse) to what people see now.