Is your technical content boosting your company - or damaging its reputation? Even technically correct content can turn off potential customers. Here are four mistakes we often see that can undermine your company’s technical content marketing efforts.
Dotting the i’s
The best technical content combines no-nonsense, factual technical information with well-honed English that flows naturally. That takes time, effort, and often the contributions of multiple people to produce.
Unfortunately, we’ve seen busy and understaffed companies publish what amounts to a first draft because they want to get “something” out the door. It’s usually written by a technical staff member who’s great (perhaps brilliant) at their job but lacks writing experience.
The piece may be technically accurate. But it’s so hard to read that most readers will tune out before they get halfway through. Or it gets so into the technical weeds that the bigger picture - the “why” - is lost.
Unpolished writing feels unprofessional. It’s hard to follow and obscures meaning. It also breaks the reader out of the flow of reading the document and forces them to focus on the flaws - like someone honking a car horn while you’re trying to enjoy Beethoven’s 9th.
Writing technical content: the most common mistakes
Mistake 1: No story
All good writing has a beginning, a middle, and an end. Technical content is no exception. It should have a firm structure that starts at the start and flows naturally through to the last paragraph.
For technical content, a good “story” means introducing each essential element of the content in a logical, step-by-step manner. In a technical tutorial, this means laying out all elements of the proposed solution in an orderly sequence. In a more conceptual or architectural doc, it may mean providing a high-level overview of the concept or architecture before diving into an explanation of its components.
Technical content without a clear story often exhibits the following problems:
- Concepts introduced seemingly at random
- Long tangents that may be interesting in themselves but don’t directly relate to the topic
- Needless repetition of points made earlier
- Repeating the same point over again but in a different way (sorry, I couldn’t resist…)
How to remedy: Creating a content outline goes a long way toward solving storytelling issues. You can also use outlines to secure buy-in from stakeholders - dev, marketing, support, sales, leadership, partners, etc. - before committing words to paper.
Mistake 2: Assumed knowledge
Engineers building cutting-edge products know their areas of expertise inside and out. They live, eat, and breathe the language of their field.
Your customers, however, are coming to your product from different contexts. They may be a junior engineer still getting up to speed on fundamental concepts. Or they may be an experienced engineer entering a new technology space (e.g., back-end developer investigating a front-end framework; SQL developer using a NoSQL database for the first time).
It’s important to know the range of your audience and what levels of experience they might bring to the table. Using too much industry lingo or assuming steps in a walkthrough could repel technical decision-makers who might otherwise have become important customers.
How to remedy: Define who your target audience is beforehand. Is it only people already deeply immersed in a certain field (e.g., front-end Web development)? If so, you can assume a certain base knowledge.
For example, you don’t need to spell out “HTTP” to web developers. If you’re selling a networking product and your target group is networking engineers, engineering managers, or similar decision-makers, you can assume a knowledge of basic networking concepts.
Is your target audience wider, or does your product introduce new concepts and approaches to a problem? Take the time to explain or provide links to more detailed information so everyone can pick up what you’re putting down. In particular, expand acronyms on first use and avoid industry jargon whenever possible.
Mistake 3: Soggy language
A basic tenet of Search Engine Optimization (SEO) is that hard-to-read content is harder to find. Low readability increases your bounce rate - which, in turn, hurts your search engine ranking.
Poor quality writing and editing also hurts your company’s reputation. A page with typos, run-on sentences, and wall-sized paragraphs of text doesn’t come across as confident or knowledgeable.
How to remedy: If possible, hire an editor or a technical writer to do an editing pass of all content before publication. If that’s not currently possible, create a style guide and set out some firm rules for writing:
- Keep paragraphs short (2-4 sentences max)
- Keep sentences short (around 25 words)
- Spell check and grammar check (Grammarly is a great tool for this)
- Delete filler or repetitive content
- Remove inconsistencies in the use of product names, voice, etc.
You can further boost organic traffic by ensuring you’ve addressed the basic elements of SEO for each published page. Use our SEO Checklist to get you started. Using an SEO plugin that works with your CMS, such as Yoast for WordPress, helps authors ensure what they submit conforms to SEO best practices.
Mistake 4: Not maintaining what you publish
Many people assume that, once they’ve written something, they never need to touch it again. Nothing could be further from the truth.
There are two reasons to keep technical content up-to-date. One is that the search engines like updated content. Keeping your content updated will improve your search engine rankings and discoverability.
Another is that technical content is highly susceptible to going out-of-date:
- Your product changes often - likely every week or (for you hardcore Continuous Deployment shops) several times a week
- Best practices change as technology evolves
- Paradigms shift - new technologies (cloud, AI) render existing solutions obsolete
If you don’t plan to maintain the content you’ve created, it’ll grow stale. What impression will that leave on a prospective customer?
How to remedy: Use a tool like Ottimo to track how your content is performing over time. For your top content (what we call in Ottimo your Stars), schedule a quick review to make sure everything is technically accurate and up-to-date. If the page is a walkthrough or tutorial, verify that all the steps work against your current product.
For content where traffic is falling off, analyze what improvements might help. Is it still technically relevant? Does it need to be longer? Is it optimized? Does it need an editing pass?
If you decide a piece of content isn’t worth keeping, remove it. That’s right - delete it from your site. Focus instead on keeping your high-performing content in tip-top shape and improving good content that could use a little TLC.
More resources to enhance your technical content
Want more ways to boost the quality and credibility of your technical content? Check out our technical facts reference database, which contains compelling statistics from across the software industry that you can use to motivate your readers and keep them engaged with your content.
