Recently someone emailed me to ask whether the posts on the Tech Writers UK Discussion group (which I manage) were mainly about software writing or engineering writing. If they were mainly about software writing, my correspondent said, he wouldn’t join the group. I found this question rather curious for a number of reasons.
First of all, the obvious way to find out what topics are discussed in an online group is to join the group. If the discussions aren’t something you’re interested in you can just leave. Next, despite my best efforts, the Tech Writers UK Discussion group isn’t a very active group.
But the most curious thing about the question was the assumption that software writing and engineering writing are different. That hasn’t really been my experience. Writing for product users needs to meet the needs of the audience. It needs to be clear, unambiguous and task focused. Facts (such as settings or parameters) need to be provided separately from step-by-step instructions. These are general rules that I believe apply equally to any sort of user facing writing for any sort of product. My corresondent did not agree. When I asked him whether there really were differences between these two types of writing he replied:
Yes, there is a huge difference between software writing and engineering writing. For example, an engineering writer may write the procedures for replacing the pantograph pan head carbon elements on a train. Many software writers develop help screens for software applications, or may write the specifications for database development. And then there are writers who fit between those two examples, such as medical, financial, governmental, etc. All are talented, just in different areas.
My area is engineering. If your group does not discuss documentation that deals with electronics, mechanics, hydraulics, pneumatics, or similar, then I would have nothing to contribute to the group.
In my opinion, what my correspondent is highlighting here are differences between the domains of software and engineering, not differences in modes or styles of writing. The same principles of clarity and suitability for purpose in writing must apply, whatever the domain. It may take longer or more effort to understand a domain that you are unfamiliar with, but I strongly believe that the principles of technical communication do not change from one domain to another.
Interesting. That attitude may explain why most of the technical communication circles I frequent (in the UK at least) have next to no engineering writers. Software companies just seem to be more vocal and more likely to use technology like social media. It is what they are familiar with.
I 100% agree that whilst the domain may differ, the skill set involved in producing content is the same.
At a recent conference I talked to someone who produced user assistance for aircraft pilots. I was spellbound by his tales of ensuring they had all the legal documentation to ensure they could manually crack the undercarriage should they need to. Likewise I’ve seen the results of someone who produced instructions for a talking defibrillator.
The challenges that those technical communicators faced are immense and their results speak volumes. The application of their work maybe completely different from adding a column to a table in Word, but we can still learn from each other. It looks like we have some work to do to try to break into these sectors if the UK Technical Communication industry is to represent us all.
David, I agree with you. The core principles of technical writing don’t vary: clarity, task sufficiency, suitability for the audience. There are certainly differences in domain knowledge — as well as differences in purpose (for example, instructional manuals vs. training content vs. policies-and-procedures writing) and format (print, web, tablet, etc.). But the commonalities far outweigh the differences.
Granted, the engineering writer might not profit from a discussion about using RoboHelp. But even then, come to think of it, wouldn’t the writer want to be at least conversant about HATs? Talk about limiting one’s options when it comes time to find a new job!
I come at this discussion from the point of view of an engineering writer. Perhaps people in the software industry don’t understand the degree to which some software writers may treat engineering writers as if we don’t exist. Software writers may make sweeping comments about, say, wiki use or content strategy, as if only a dolt would do things differently than they do. Engineering writers have far different requirements when it comes to user-generated content or printed publications. We don’t want to be bombarded by messages from people about the “right” way to do something when those people clearly haven’t given a moment’s thought to our business needs.
Also, software writers use different jargon than engineering writers. For instance, I assume HAT means help authoring tool, but how would I know that if I don’t use a help authoring tool? Good technical writers understand how jargon use can make readers feel excluded. Well, engineering writers feel that way a lot.
When it comes to writing style, I don’t think there’s a difference. But the business needs are very different. So if the forum is geared toward the software industry, then an engineering writer may not get much out of it.
David, I’m with you. What is essential to both domains is the skillset. The content for any freelance writer, or business, varies dramatically. Last year, we were writing for a software house, this year, we’re writing for the aviation industry at the same time as an educational content producer. Yes, I’d bracket it all loosely as technical writing, as in some cases, it does get very technical, detailed, involved, with instructions, diagrams, tables, spreadsheets, flowcharts, procedures, photographs and illustrations. But, to assume a forum would only cater for the needs of writers in a very specific area seems to miss the point. A forum is for sharing ideas, and we only talk to those who write in exactly the same areas, we lose something that other professional writers have to offer, namely a new perspective. And that is what forums and discussions and blogs are all about.
David, it sounds like your correspondent emphasised a difference in domains (software vs. engineering) – but to me it seems more like a difference in attitudes: How widely do you cast your networking net? How far do you search for inspiration? And there is no right answer, it’s just a matter of personal preference.
Personally, I’m into arts, both visual and musical, which gets me into questions of motivation and creativity. And to me it’s interesting and satisfying to apply those to tech comm. Other tech writers don’t think tech comm is creative, much less art. And I’m not sure such discussions ever manage to change anyone’s mind – precisely because it’s not about focus (domain vs. mode), but more fundamentally about one’s attitude and general outlook on one’s job and one’s life.
Some classical musicians don’t feel they have anything to contribute to jazz, to others such distinctions are close to meaningless.
This should be the primary discussion in the technical communication field. I wonder how much influence hiring practices have on technical communicator’s attitudes toward the value of technical communication fundamentals in addition to domain knowledge. Are writers hired based on what they already know rather than their ability to gather, synthesize, and convey new information? And is that hurting technical communication in general?
I’m not in the UK, but as a US freelance technical writer I find tech comm to be quite creative (but maybe I am in the minority based on Kai’s experience). Graphics, videos, even just the use of particular fonts or text colors can make a big difference to communicating a topic well.
For instance, while I studied electrical engineering in school so I understand that domain too, I typically work on user manuals for software products. Perhaps further afield, I just completed a several hundred page FrameMaker manual for a new K-12 school safety program complete with detailed physical exercises for each topic. Parts of the program were straightforward steps(how and when to call 9-1-1) and other parts were pretty sensitive (good and bad touch). Lots of facts and background information were provided, but one of the key goals was to distill the lesson information down to a one page sheet that the teacher could easily take out an use in that day’s lesson plan.
I used a lot of graphics as visual clues, for instance the lesson objectives on an image of yellow note paper, a skeleton key for important terms etc., so that the teacher could very quickly refer to the sheet as they were teaching and leading the discussion and find what they needed. Your engineering writer might believe that discussing this project had nothing to do with documenting hydraulics (thus of no use to him), but I would beg to differ. The more examples and methods we can share to help our users illuminate the subject (no matter the domain) the better.
Andrea’s point about excluding writers also applies to many software tech comm’ers who have good reasons not to constantly be on the cutting edge of the industry. Either because their industry is regulated or because their market is “behind the curve” a bit. Bluntly speaking, there’s no use in making docs look like 2012 while the software itself and the underlying operating systems, browsers, etc. at customers look like 2007. Mobile documentation, HTML5 and SEO are important to some, no doubt, but in some markets it simply doesn’t apply at the moment. Knowing your audience also applies when selecting suitable technologies – which may not be the latest craze.
I think you’re both right. There is a difference between documenting an API and writing a maintenance manual for a defibrillator to component level. However, I have done both. The writing process is largely the same but the expertise is different. I was able to describe the circuit functionality to component level because of my electronics engineering background so I didn’t need to spend much time with the circuit designers – in fact a common comment was “so that’s how it works”. On the other hand I had to work closely with the software engineers on the API documents.
It sounds like most commentors agree that the writing principles are the same. The goals, such as ensuring that the information is relevant, clear, and findable, are the same. The activity of gathering the information may be quite different. Knowing mechanical systems aids the writer immensely in asking the right questions, finding the missing info, picking engineers’ brains.
(I have done both, including interestingly, writing defibrillator documentation that won an STC award.) One of the differences in SW documentions is that it requires fewer photos/SS/graphics since the UI is right there with the documentation.
And to Kai I say, I do think discussion changes writers’ minds about creativity and ‘art’ in documentation. That is why I wrote ‘Creating UA with an Artistic Eye’.
And to Andrea I would say, some articles lean toward tools or processes that favor one domain over the other. It does seem like tools for SW documentation seem to get more press; that signifies nothing.