In a recent discussion thread on LinkedIn, someone asked for opinions about the job description for a vacancy for a “Programmer/Writer”. Was it possible they asked, for someone to be both a software programmer and a technical writer? Was it true that only someone who was a programmer could understand software well enough to write about it? Or was it a misunderstanding of the real role of the technical writer? Read more
Tag software development
The best place for a tech writer
I have spent most of my tech writing career working with product development teams in software and other hi-tech industries. It is what I enjoy doing. It’s what I do best. And I have come to the conclusion that it’s not the best place to be.
That conclusion may surprise other tech writers, and it did surprise me a little as well. Usually the discussions are about whether the tech writers should report to marketing, or to customer services, or to development. The general consensus is that being part of the development team is best because daily contact with engineers and developers helps tech writers understand the product features they need to explain. It’s also a good place to be because the end-user documentation, like the product itself, is usually seen as a deliverable item.
Let’s look at this question from a slightly different angle. Where do shared interests lie? Marketing are interested in pre-sales – getting new customers in. Customer services are interested in post-sales – keeping existing customers happy. Development are interested in engineering and in code.
Did you notice the subtle difference there? Development aren’t really interested in customers. Of course, in general terms they want the company to have customers because they know that’s where the money to pay their salaries comes from, but their day-to-day focus is not on customers. The tech writers’ focus is on customers, or at least it should be. That’s why we share so much affinity with usability and user experience people, and with training people. That’s why we try to write end-user documentation that is about tasks people have to do, rather than about features the product can offer. That’s why we don’t really fit in to a development team.
Where would the ideal place for tech writers be? I’d say that we are part of the team that looks at customer needs and how they are met. That would be a team with a slightly wider viewpoint than the development team, and I would call them the product management team. (I know that “product management” in many organisations is a marketing function.) Product management would have the responsibility for delivering useful tools to customers, and those tools include products, task-based documentation, training, and support. Where this kind of product management team doesn’t exist sticking around the development team is clearly the preferred option, but I’d say it’s not ideal.
Beware the Default Manual
Thomas Barker, in his book Writing Software Documentation, uses the term “the default manual” to describe a user’s guide that is organised according to features, rather than tasks. This sort of user’s guide has a chapter for each menu in a software program, and a section for each command. (For hardware, which Barker’s book doesn’t cover, it would describe every switch and button.) Barker rightly explains that this sort of manual is not really very useful for users. The information in a default manual, and in particular the way the information is organised, bears little or no resemblance to what the average user needs to do in their everyday working life. Like the old (and unfair) joke about Microsoft Customer Support, the information given is totally accurate but absolutely useless. In short, default manuals are the sort of things that give technical writing a bad name.
Like Barker, I believe in the importance of user focused documentation, and try never to write default manuals. Unfortunately a lot of my customers have yet to understand the difference between effective user assistance on the one hand, and the only kind of user manual they have ever been exposed to on the other, and the default manual is what they ask me to produce. I don’t always succeed in convincing them that their users deserve something better.
Barker does not discuss why default manuals are so prevalent. I can think of plenty of reasons. First of all default manuals appear to be quick and easy to write. They are based on the product’s features, so the structure of commands in user menus offers an instant structure for the manual, and an instant checklist to ensure that every thing is mentioned. Since they describe program features rather than user actions they are easy to write. Even the most junior programmer on the team knows that the New command on the File menu creates a new file. That’s why so many default manuals are indeed written by the most junior programmer on the team.
Default manuals reflect the developer’s world-view, or more accurately the development manager’s world-view. The development manager rarely sees any feedback or comments from customers, and has probably never spoken to a real life customer either. For development managers, thinking about users doesn’t just take time and effort, it requires a degree of objectivity and critical detachment from their work that was never part of their job descriptions. They have goals to achieve which are stated in terms of objects coded, features implemented, and overtime hours saved, not in terms of user task fulfilment or customer satisfaction. Those things have no relevance to their jobs or to their end-of-year bonuses.
The lure of the familiar is also significant. Like travellers’ tales of exotic creatures and peculiar peoples, the idea that a different and better way of writing user manuals might exist is regarded with more than a little scepticism by many in the developer community. Default manuals are all they have ever known.
A third reason for the popularity of default manuals is that they are an easy way of demonstrating that the development team’s “contractual obligations” have been met. I am thinking here of “contractual” in the broadest possible sense, and including not only written undertakings to external customers but also internal agreements and understandings with stakeholders within an organisation.
Default manuals are popular because they appear temptingly simple and easy, and because they can be shown to correlate directly to the product features. They can be written cheaply by an existing member of the team who won’t “bother” other developers with questions that waste their valuable time. Once they’ve been done, the development manager can tick several boxes at once – there is evidence that all the required features are there, the program’s features have been checked by a competent person, and hey presto, there are user manuals as well. In this scenario no-one is surprised or worried by the fact that the manuals will never be opened, let alone read. That was never anyone’s intention.
Fighting back against the default manual culture is a challenging and difficult undertaking, especially if you are the only professional writer around. But it is a noble cause and one that all technical writers should pledge themselves to.
At last, some consideration for users
As I work extensively with companies developing computer software and hardware, I am proud to be a member of the British Computer Society (the BCS). I receive regular emails and magazines and occasionally attend local meetings. This week an email newsletter alerted me to a blog by John Morris on the BCS web site entitled “Data Migration and User Stories“.
Morris writes in praise of “User Stories” used in Agile programming which are (and here he quotes from Wikipedia) “A software system requirement formulated as one or two sentences in the everyday language of the user”. When I read this I didn’t know whether to cheer or to weep. Here is a technical expert in a highly technical field who is at last paying attention to the fact that the system he is building needs to be used by real-world end users – not techies or geeks – to do real-world jobs. I suppose any consideration of user needs is a huge improvement on no consideration at all, so I think I’ll err on the side of cheering.
But putting the needs of the real end user at the focus of technology projects is something everyone should all aspire to, and technical authors, usability specialists, and interface designers have been fighting on behalf of real end users for decades. It’s been a fight because in most cases software developers and other technical experts dismiss our concerns because we’re not programmers. The only things that are new about Agile “User Stories” is that a it’s a cute name for thinking about real end users, and it’s part of a popular development methodology which happens to be the latest trend.
I’ve not been a big fan of Agile, because in most of the implementations I’ve seen the daily scrums and the like focus on minutiae of code, and the big picture goals – helping real-world end users do their jobs – get lost. But if Agile development teams really do develop user stories, and really do keep referring back to them to make sure their project is on track, then there is a glimmer of hope.
