4 Hard Problems in Technical Writing

A representative sample of common technical writing problems could include:

• Day-to-day challenges around tools, processes and methodologies;
• Getting the correct information from the right people in a sensible time frame;
• Lack of experienced API writers;
• Transitioning to DITA and/or entirely electronic documentation.

Let's not pretend that I couldn't have chosen a hundred other problems instead!  But these will do as good examples of day-to-day problems that can be dealt with on a tactical basis as and when encountered.  

Struggling to get information from the developers in a timely fashion?  

Kick the development manager to get the team to do their job.  

Struggling to hire a full-time API writer?  

It's a supply and demand skills shortage, so either do it 

yourself or suck it up and pay for a contractor.

Struggling to move from hard-copy-using-templates 

to DITA-with-electronic-delivery-only?

Join the club, it's a right slog.

These are problems that basically require more resources, more procedures, or simply better management.  They're not heavy structural issues that will defeat the finest minds in the business, they're part of what it is to have responsibility for documentation.  So there are problems like these, and then there are problems.  This article is about the latter - the hard problems of documentation.


What is a "hard problem" in this context?  Well, there's no maths involved, which rules out NP-Hard problems (if that doesn't ring any kind of bell with you, don't click the link.  Life's too short. Literally.), and we're not at the level of the hard problem of consciousness, so you don't need to start reading Descartes.  Our problems are somewhat less studied than these big beasts, but they have proven to be no less intractable for our profession.  In short, they are the big, structural, strategic problems that cannot be solved by one person or one team, and they are:

1 - How to objectively measure documentation output.
2 - How to document the Internet of Things, especially the ever growing number of integration points.
3 - The lack of standardised writing certifications.
4 - An industry culture that assumes a documentation cost rather than a documentation value.

Each of these 4 problems has one thing in common: The requirement for a recognised, standardised global model that allows people to track and measure success (or failure).  I said that there was no maths involved, but that may have been slightly presumptuous; measurement by definition involves some form of maths, and perhaps there lies the rub.  Documentation is seen as an inherently qualitative activity and as such most people think that it can't be measured.  If you can't measure something, you can't compare it to other things, even of the same type.  If you can't compare it, you can't do any quantitative analysis on it.  If you can't do any quantitative analysis on it, you can't put a standardised value on it.  If you can't put a value on something, it's a cost.

There are possible solutions to all 4 of these problems, but any viable solution requires a recognition within the industry that solution x is the correct answer to problem y.  For example, there are some good providers of technical writing training, but there is no definitive qualification which says "This person is a competent technical writer".  We need the technical writing equivalent of "Certified Scrum Developer", "Microsoft Certified System Engineer", "Project Management Professional", and so on, qualifications that everyone recognises and which enable recruiters to sort the wheat from the chaff.  Otherwise we are like the world of boxing, where there are 7 or more "World Champions" in every weight division and no-one is really sure who is good, and who's just had good management. 

Similarly, being able to apply some agreed forms of measurement to documentation would enable a meaningful comparison between the work of different writers, or the output for different products, or between different companies.  Critically, it would also allow a clear understanding of the strengths and weaknesses of the documentation so that improvements can be identified and prioritised appropriately. 

I'm not suggesting that this can't be done, but there is no globally recognised, objective measurement system.  This is a close sibling of the problem we face when understanding how to document the Internet of Things and the functionally limitless number of integration points.  A good example of a question within this space would be "Which side do we document from, and do we need to document from both sides?", i.e. where product A can be integrated with product B and vice versa, do we document the integration from the perspective of product A or from product B, and should we document from both sides?  Having a variable, mix-and-match approach to this kind of question only sows seeds of confusion that sprout into feelings of annoyance with inconsistent or apparently incomplete documentation.

It is only when we have answers to these hard problems that we can properly call for a cultural shift towards one that sees the value rather than the cost of what we do.  Any individual can make the effort to change the culture of their current organisation, and they might well succeed, but as long as documentation lacks agreed quantitative metrics and methods, the default attitude of many decision-makers will remain as one that sees documentation as nothing but a cost.

I don't know what the answers to these questions are, although I have some thoughts that I'll share in future posts.  But I do know that the answers that we agree on as a profession will have long-lasting ramifications for all of us.