In developing our new Technical author basic/induction training course modules, one thing that struck us was it is easy to talk about a technical writing process that is often not followed in reality.
For example, most books on technical writing describe how the writing project begins with a planning stage, an activity where the project is carefully mapped out in detail. The reality is often quite different, and planning is often considered far less than a trainee Technical Author might imagine.
Many Technical Authors believe they already know their audience and the appropriate purpose of the document, so in a project with tight timescales, the planning stage can end up being minimised. The reality is that writing projects are often a recursive and iterative process. For example, the purpose of a document might revisited at the review stage. This decision may not be right, but it’s one that often happens.
Today, Technical Authors can be expected to describe a product in permanent beta, developed in using Agile methodologies,(EDIT) or using a single-sourcing tool. Times have changed, and the way Technical Authors carry out their work, to an extent, has done as well.
We’ve decided it’s wrong to pretend certain things don’t exist, and mention them in the course. Hopefully, it will help new Technical Authors identify where there are potential failings in a project and be able to make a justifiable case for certain activities.
Do you think this is the correct choice to make?
Absolutely true. I found that short deadlines, pressure from clients, and real-world chaos force us to take shortcuts. The only problem is, that when it comes to customer-facing documents, you have to get it (at least mostly) right the first time. This may very well call for a combination of excellent planning, superior writing skills, and a whole bunch of luck! I’m not sure my TW teachers ever mentioned that…
I always start with “in an ideal world … but what really happens is this”.
Of course. Being flexible, responsive and efficient are character traits as much as professional skills. A lack of protectiveness over your work when the goalposts move helps.
Yes, certainly that’s the right way to teach new technical writers. I made the same decision a couple of years ago in the certificate course that I teach. I used to say “Over my thirty-year career the basic Tech Comm process has changed very little.” Then one day I realized that I was lying to my students.
It’s still possible to plan documentation projects in agile (or agile-like) environments. Just not in the same highly structured way we used to do it.
Absolutely. Let’s not pretend that 1950s style waterfall planning works or exists in the modern world. A plan is only a good as the information it is based on. A approach that calls for everything to be planned before anything is done can only succeed on the assumption that no new information will come in during the entire development cycle.
That was not true in the 50s, and it certainly isn’t true today. So lets not present waterfall planning was an Eden from which we have fallen. It was a bad way to run a project in 1950, and it is a terrible way to run a project today.
The way in which we approach and plan our work must be founded on the expectation that new information will continue to be created and discovered during the entire development cycle of a product and its documentation, and that both the product and the documentation will be expected to adapt to that new information as it becomes available.
We should not decry this situation, or wish to work in companies where this does not happen. There is a word for such companies: bankrupt.
The constant flow of information, and the need to constantly adapt to new information, is not a flow or a problem or a disruption — it is the nature of modern product development. It can be managed well or managed badly, but it cannot be managed out of existence. We should be preparing young technical communicators to operate efficiently in this environment.
I completely agree that practical training needs to be realistic, so I have no argument with you there. Just one small quibble, though. You appear to suggest that a software product built using Agile methods is “in permanent Beta”. I don’t agree with that. There is no “beta”, the customer’s feedback on this month’s released software should inform the updates to next month’s release. If Agile is done well, and if tech writers are allowed into the process, this constant feedback loop is a marvellous opportunity for writers to learn more about how users actually use the products, and to understand how best to support them. But as you know, and as I am sure you point out in your honest and realistic course, Agile isn’t always done well, and tech writers aren’t always let into the process.
I didn’t mean to suggest that Agile based projects are in permanent beta. It’s a phrase I’ve heard with regard to Web applications, where software updates can be on almost a daily basis.
I’m all for teaching tech writers applicable and useful skills. But aren’t we cheating our students and cheapening our profession when we only teach them “good enough” by whatever conditions prevail?
I think we also need to teach what “tech comm done right” looks like, so our students can develop their own standards and judgment of what “good enough” is. And it’s not when the deadline arrives or the money runs out.
I might suggest training technical writers the way Marines train their recruits: Hope for the best, but prepare for the worst. Cover all the bases that way.
The idea of the “writing project” is often at fault. OK, there are projects that are only to do with communication (public health campaigns, for example), but most tech writing is part of a development project. The writer might well be closer to the developers and testers in his feature team than he is to his fellow writers.