"Modern Technical Writing" by Andrew Etter is a fantastic book

If you are a technical content professional, or you work alongside technical content professionals (for example, you are a software developer), and you haven't read Andrew Etter's Modern Technical Writing, please go and buy the book.

It costs less than 5 bucks, it's only 10,000 words long, you'll likely read it in about an hour, and it's spot on.

Andrew is an advocate of useful, discoverable, searchable, and scannable documentation based on user research and informed by visitor behavior.

I'll go forward and grab some quotes from Andrew's book, mixing them up with my comments.

Technical writers aim to produce content that their intended audiences will read and find useful.

Not content that is complete or formal. Not content that makes you feel overwhelmed just by looking at it. Not content that is driven by your product's internal organization.

Go for content that is easy to consume and that helps the reader achieve whatever they're trying to achieve.

People have better things to do in life than reading docs. If they make the effort to read your docs, helping them succeed can very well be the difference between abandonment and activation in your product.

Technical writers, first and foremost, are testers and researchers. Your job is to know what people want to achieve and precisely how to achieve it.

This is from the first paragraph in a section called "Don't write". A section called "Don't write" in a guide to writers doesn't exactly feel like a great idea, right?

Wrong. Before writing, you research a ton of things:

• Why was a certain product change made?
• What problem was it expected to solve, if any, or was the change made simply because it could be made?
• Does it look like the solution matches the original problem?
• What are typical usage scenarios? Which of them are currently supported and which are not?
• Does introducing new functionality have implications for existing usage workflows?
• Before introducing new functionality, how did users solve problems that it addressed?
• Are there clear migration paths that should be documented?

Seriously. Any writing that isn't simple compilation of existing content is 90% research, 10% typing.

"What is this product? Why would anyone want it?" These two questions are incredibly challenging for the average technical writer, a group of people much more focused on how than what or why. I've struggled with them many times. But if you can't answer these questions, you need to go back to the research phase, because you don't understand your audience at all.

Alas, sometimes there's no satisfactory answer to "Why would anyone want it?" — it was done because we could.

In fact, the problem is not specific to technical writers. If only all startup founders knew exactly what they were doing and why anyone would want it, we'd live in a much better world.

Writing should be the minimum possible length.

Off the top of my head, I can see a few reasons why technical writers may want to write longer copy than necessary:

• They want their work to look respectable.
• If they're working on existing documentation that struggles from verbosity, they want to conform to established style.
• They lack knowledge of what they're writing about, and as a line of defense, they bury their insecurity in word count.
• They are paid per word.

Getting paid per word is a beast of its own. As to the other reasons, come up with a healthy set of best documentation practices, add willingness to learn your product and your users, and you have a good chance to fight the verbosity plague.

... managers who treat the Chicago Manual of Style like a holy text and would rather produce minimal value from a lot of work than tremendous value from far less work.

This resonates with me in two ways.

First, I find manuals of style overrated, and I'd much prefer extensive use of manuals of substance.

Second, people who prefer to do a lot of work with minimal return are killing me. This behavior is by no means limited to technical writing or managing technical writers. Just look for people who:

• take part in all discussions in order to be visible and gain authority instead of getting the job done;
• bury job progress in excessive research and find themselves unable to make decisions at crunch time (or any time);
• start ambitious projects without considering if they can actually solve any significant problem.

And don't forget to look in the mirror, too. Do you act like this sometimes? If you do, you can do better.

However you decide to write and distribute your documentation, you should do it in a way that encourages others to contribute.

Storing content directly in XML-based languages like XHTML, DocBook, and DITA dramatically reduces people's ability to contribute.

For technical writers, the most important reason to use DVCS is that developers prefer them.

Developers will probably be unhappy with documentation anyway.

However, if you want them to be something more than picky, annoying, frustrating critics or your work, make contributing easier for them:

• Use a Git repository for your docs.
• Use a clear, established contribution workflow like GitHub pull requests or GitLab merge requests.
• Use Markdown (or at least reStructuredText) to write and maintain your docs, and a documentation generator like GitBook or Read the Docs to convert them into something that's easy to read and navigate.

If docs and the codebase are in the same repository, contributions from developers are most likely. Worst case, even if developers don't start contributing, they don't have an excuse to keep bitching anymore.

On the other hand, developers on your team may not be your best allies when it comes to contributing. Developers tend to know the internal organization of the product they work on, but they often lack in understanding of real-world use cases and workflows that their engineering work addresses.

If you're looking to improve your knowledge of the practical use of the product you're documenting — and you should — then strive to include product managers, product marketing managers, analysts, UX designers, support engineers, and solution engineers. Depending on how technical these people are, you may or may not be able to make them contribute directly. But even if you can't, you can always interview them.

Finally, you may want to make your documentation available for everyone to contribute — that is, make it open source. By doing so you can potentially involve users, partners, community leaders, or even people who want to be hired by your company. You won't necessarily make all of them active contributors, but at least you'll be able to set up an additional feedback channel, collect input in a transparent way, and build the sense of purpose by helping your audience solve their issues directly.

In short, for a wiki to make sense, your documentation should be uncontroversial and never need to be versioned. You also shouldn't mind writing in an inferior editor, only working online, and maintaining a piece of enterprise software.

This is a great summary of limitations imposed by CMS-based documentation. Even if you don't literally have to maintain a piece of enterprise software because you use CMS as a service, having a copy of docs for each product release is a nightmare both for contributors and for readers.

Technical writing doesn't need to be complicated. Technical writers have just spent several decades convincing people that it should be.

Often, people will go an extra mile to make their work look more complicated than it really is. Why?

• Do they want a higher level of job security?
• Do they want to feel better about their impact?
• Do they lack experience to have a taste for simplicity?
• Do they want to prove their worth to their engineering workmates who may not be appreciative enough?

Possibly. Whatever the reason, keeping things simple is rewarding. Not only can you make life easier for yourself and those depending on your work, but you can enjoy the sense of achievement when you're over with the work, and move on to new endeavors.

1. Learn everything about a subject.
2. Write down exactly what an audience needs to know and no more.
3. Make the content beautiful, discoverable, scannable, and searchable.
4. Consider everything a draft, and iterate relentlessly.
5. Make contribution simple.

This is how Andrew sums up the book. Short and simple.

Seriously. Just go buy it:

• Reading this book gives technical content professionals more value than all manuals of style combined, even if they learn them by heart.
• To software developers, product managers and others who work alongside technical content professionals, it helps set expectations and tell a great technical writer from someone who may need to up their game.