Is Technical Writing Either an Obligation or an Opportunity?

In the software industry, technical writing is sometimes a Cinderella, but that’s underestimating the opportunity to improve the business through writing

Map by the author

Suppose you are not a technical writer and are in charge of deciding the budget for technical writing. Which criteria should lead you to choose?

Value

First, what’s the value of technical writing for your project?

I see two possible answers:

1. Technical writing is an obligation because the project deliverable requires instruction manuals to enable users to get things done.
2. Technical writing is a step in designing the project deliverable to make it easy and practical.

If you go for the first answer, technical writing is a mitigation of the design failure in delivering the most direct possible experience to the users of the project deliverable.

Don’t get me wrong: there are industries where the “most direct possible experience” requires massive instruction manuals, and that’s not a design failure but the only viable way. In these cases, what I’m writing here cannot apply, and answer 1. is the right one.

Instead, consider the many cases in the software industry in which many instruction manual pages are the result of

• Lack of automation: users have to perform actions that the software doesn’t do but are necessary for the software to work.
• Poor user experience: users have to perform actions that are not intuitive for their mindset.

Technical Writer’s Mission Is To Write No Instruction Manual, as Far as Possible

In both cases, technical writing mitigates the lack of software: the instruction manual tells the users what the software cannot do and what the users have to do in place. That’s an obligation: the deliverable must include the instruction manual. Otherwise, users would not be able to use the software. That’s the result of poor design.

Instead, technical writing as a tool in software design becomes an opportunity.

Why?

Technical writing, empowered by languages like Domain Driven Desing, allows exploring software’s behavior before building it.

That’s extremely helpful because it provides the opportunity to incorporate the control of the software’s user experience while designing it when it’s much more affordable to change and adapt.

At the end of the day, it’s common sense: if you tackle problems in advance, solving them costs much less than reacting later. Technical writing as an opportunity is the same: a proactive tool to detect and solve logical and user experience problems in advance.

Budget

Then, what percentage of the budget should you dedicate to technical writing?

The answer comes from experience by evaluating: “How much rework do you have to pay on average in your projects? And, what percentage could you have saved — about the already completed projects you know it — with a more efficient design approach?”

Rebase the expected cost saving on the project’s entire cost, and you’ll have a reasonable percentage of the budget to dedicate to technical writing.

You’ll notice an essential assumption in the evaluation above: I’ve tightly connected technical writing and design.

Why?

Following Wikipedia:

A design is a plan or specification for the construction of an object or system or for the implementation of an activity or process or the result of that plan or specification in the form of a prototype, product, or process.

Crafting a plan is a complex task that requires clarity to succeed. Technical writing aims to simplify the language of complex topics. That’s why technical writing is an opportunity to help design and, consequently, should be part of the budget dedicated to design.

Conclusions

It’s all about clarity, and clarity is a mindset.

When the mindset is technology-centric, technical writing can only be a mitigation: so, an obligation.

Technical writing, empowered by languages like Domain Driven Desing, allows exploring the software’s behavior before building it.

Instead, when the mindset is user-centric, technical writing acts in advance by bringing the voice of users to the design phase; in this way, it is an opportunity.

If you enjoyed my article and found it helpful, please consider joining Medium through my referral link: you’ll support my writing and get into a sea of knowledge. No extra costs!