How to avoid being a secretary for engineers
- Critical inquiry versus vocational knowledge
- States of mind
- Examining a different why and how
- Nice try, but still short
- Making the intellectual work visible
- Conclusion
- Short feedback survey on this post
- References
Listen here:
Critical inquiry versus vocational knowledge
Lately I’ve been thinking about two types of knowledge: intellectual knowledge versus vocational knowledge. Or rather, critical inquiry versus technical how-to. Or theoretical knowledge versus practical knowledge. In short, asking why versus asking how or what. I’m not entirely sure how to characterize the differences, but the difference in focus has contributed to some angst in my tech writing career lately.
Rewind a bit to my previous posts on trends (such as this one or this earlier one), and you’ll find that I’ve been wrestling with the question of whether to be a generalist or specialist. Regardless of any generalist/specialist outcomes around research and what employers want, etc., it’s hard to escape this one critical fact: you can’t write without knowledge. Unless you have a more solid technical grounding, you just can’t write much about those topics.
Consequently, in order to be a rock star technical writer (rather than just a supporting editor/publisher for SME contributors), you have to move into the technical knowledge domain to some extent. Not necessarily becoming a specialist, but you have to accrue more understanding of the subject than a generalist might have.
With this realization, I decided to sink some dedicated time to simply learning tech every day. For a week at work, I decided that I would do 3 tech pomodoros at the start of each day (a pomodoro is a 20 minute session of focused learning — it’s my approach to learning). Given the many interruptions and needed emails to respond to or meetings or fires to extinguish, etc., I often wouldn’t finish my 3 tech pomodoros until noon. After a week of this, I found that my productivity plummeted at work. It seemed I wasn’t accomplishing nearly the same as what I did previously.
So I decided to put the tech learning on pause for a bit to catch up and make more progress on some high-priority documentation tasks. I threw myself headlong into documenting what was one of the more challenging tasks on my plate. But as much as I tried, I realized that it was an extremely complicated subject and not one easy to make progress on. Since the requirements document that engineers gave me as a starting point assumed so much technical knowledge already, the documentation was really slow-going.
It’s challenging to write documentation for senior level engineers. Moreover, it’s challenging to write about anything when you only have a partial knowledge of. Presumably, the tech pomodoros I was doing should increase my technical knowledge for the needed documentation, right? Well, the plan sounds good in theory but in practice doesn’t always work out. The documentation tasks at work require an advanced level of knowledge, which I can’t just absorb from google searches or other quick tutorials. I need the e-learning courses that build from ground zero and move through novice, then intermediate, and later to more advanced topics.
Which brings me back to my dilemma about being a generalist or specialist. In order to accrue the needed knowledge to be productive in authoring content (or even just editing and structuring it), I need to specialize my knowledge a bit more. Trying to write coherently about something I only partially understand is frustrating, though I guess this feeling captures much of the heart of what it means to be a technical writer. Mark Baker explained in a comment on a post about technical acuity that “All professional technical communicators are … by definition, underqualified for the work they are doing. … The best person for each individual job is the one who comes closest the virtually unattainable combination of rhetorical and technical acuity and knowledge that each individual job requires.”
And why are technical writers unqualified? It depends on the level of complexity you’re documenting, for sure. But for deeply complicated coding tasks in the developer domain (those topics intended for senior-level engineers), the generalist technical writer’s background will come up short. This is why I decided that if I want to both survive and thrive in developer doc environments, I needed to step up my technical game by purposefully and deeply increasing my technical aptitude. Hence the regiment of tech pomodoros each morning.
The problem and angst, though, is realizing that the sort of technical knowledge I need isn’t the kind of knowledge that excites me. I don’t find vocational knowledge nearly as exciting as critical inquiry. I’m much more interested in why questions than how or what questions. Yet the tech learning focuses almost exclusively on how or what knowledge — how to build things, from an engineering point of view, what a particular technology does, how you interact with it, etc. If restricted to how or what questions, technical writing is more of a sub-discipline under engineering than a focus in the humanities discipline of rhetoric.
States of mind
This dichotomy between these types of knowledge reminds me of a response someone provided to a recent survey I conducted. A while ago, I created a survey on my blog about practitioner and academic collaboration. One of my questions asked, “Do you trust advice academics might provide on professional practices, on theories that should guide action, or some other factor? Why or why not?”
One of the respondents said:
For the most part, I’ve trusted advice from academics when it related to research findings; although, they don’t have the same perspective as me because I’m in the real world, and they’re outsiders just talking about a world of which they’re not belonging. For example, an academic told me that graduate school promoted arguments, and graduate students need to learn to disagree. In the real world (aka professional world), arguing with others and disagreeing does not help the business. Instead we need to work together to identify what’s best for the business. As tech writers, we need to find ways to add value, but we don’t need to waste time disagreeing with others to develop “interesting” conversations. That’s not why we’re brought on board. Clearly, that academic’s perspective did not reflect business sense, so I trust their advice, but I know enough to know they could influence me to do something that’s not in my best interest (professionally).
In short, when the respondent says “graduate students need to learn to disagree,” he or she is saying academics invite students to think critically and challenge assumptions. This is the general direction of knowledge in the academia: moving towards openness, asking questions, investigating assumptions, distrusting the motives and agendas, showing how seemingly simple ideas are more complex, or how complex ideas are actually simple, etc. Bonus points if you can deconstruct someone’s logic and show how the premises are all a paradox. It is exactly this kind of critical thinking that I learned to love. It’s why I majored in English and later earned an MFA in literary nonfiction writing.
I remember once during my MFA program, I decided to write an essay by digging as deeply as possible into a seemingly trivial topic. I would start at some benign point, but then begin asking questions and more questions and more questions to see how interesting of a direction I could go. At times it was exhilarating to see the different topics and trajectories play out. And then equally challenging to figure out how to present and structure the journey in a literary essay.
As I taught composition to undergraduate students, I came up with a formula for a thesis statement that was guaranteed to work pretty much every time. When students turned in essays that had boring, obvious thesis statements, I suggested they revise them with this approach: Although many people think X, actually Y is the case. This forced students to think in unconventional ways, to value looking from different, less commonly held perspectives and to explore alternatives to the norm. In some ways, this mindset captures the essence of the humanities academic perspective.
All too often, I feel like this element of critical thinking is missing from the documentation projects in the workplace. Instead of critical inquiry, that thought journey has already been taken by the product team and engineering group. The product team analyzed the market need and came up with a product solution. The engineers applied their minds to determine the best way to build the product. They might have evaluated different information system models, different code languages and approaches, and more. When they finish, they feel that the creative solution has been achieved. What’s left is merely to document the solution. And that’s when they reach out to me — to come in after the thinking has been done to merely describe what was built.
Here is where technical writing can become very boring as a career. If my only task is to “document the solution,” where is the fun in that? Where is the critical journey, the inquiry and the adventure in figuring out the puzzle? Where is my ability to “disagree,” as I learned in graduate school? What assumptions can I challenge? How can I interrogate a topic and ask my own questions?
This mindset and scenario makes tech writing a chore and a profession that would be best titled “Engineering Secretary.” It’s suffocating for someone with a creative mind.
Examining a different why and how
Well, if that’s the extent of a tech comm career, this would be a very short and sad post. However, I believe this short-sells the tech comm profession in significant ways. In reality, technical writers have a problem to solve as well: why take a certain approach rather than some other? Why aren’t more users adopting the product, or having success with the implementation? How should we communicate this very complicated information in easy-to-understand ways? These are questions engineers rarely consider, but they should be the problem that technical writers wrestle with.
Let’s return back to the requirements document I was trying to make sense of earlier. Engineers laid out the basic information users would need to know, and they hoped that I could just run with this information and make it understandable for users to implement. But not only is there a vast difference between a requirements document and user documentation, even as a requirements document, the information was barely readable. Not just poorly worded sentences, but no sense of organization around implementation tasks. The document was heavy with jargon, assumptions all over the place, no sense of audience or structure, and other issues (such as lengthy bullet point after bullet point, sub-bullets and sub-sub bullets). It was the kind of document that only makes sense to people who have been meeting for months to discuss the content in person.
As a technical writer, it’s easy for me to forget this more creative component to my job: figuring out how to present complex information, why I should take certain approaches rather than others. Could it be that figuring this conundrum out is just as complex as the technical solution itself? It depends on the degree of complexity behind the information, for sure, but for a really meaty technical task, creating the documentation might be a significantly challenging project worthy of its own study and critical inquiry.
Think about how often documentation fails for users. It might fail due to the varying technical backgrounds of users, the jargon in the technical domain, the many permutations and options around configuration, the contrasting business goals among users, and more. Creating documentation that simplifies what is truly complicated for users can be a real puzzle. This is part of the reason I started a whole series on Simplifying Complexity. It is no trivial task to make complex information in the technical domain simple for users to understand and follow.
Beyond just working with words (and sentences and structure and organization), we also bring to bear our publishing expertise to execute on solutions to the problem of simplifying complexity. This is why I dive into publishing tools and techniques more than most technical writers, and why I can geek out on Jekyll. It’s not just that I like authoring tools and publishing workflows. It’s because I use authoring and publishing tools in service of my larger goal of simplifying complexity.
For example, in unraveling this documentation challenge I’m currently working on, there are large chunks of code. I realized that it would really be handy to include line numbers in the code samples so that I could refer to different parts of code during the conceptual explanations. How do you get line numbers to appear in your code samples? It’s not immediately simple. Even GitHub does not support line numbers in code.
I learned how to use the linenos parameter with Jekyll’s highlight tag, but the rendered HTML for pre blocks included tables and was a mess to sort out with CSS. The PDF version of the line-numbered code with line wraps was a hopeless wash, but the online version worked well enough.
I bring this expertise with the publishing tools and technologies (HTML, CSS, and JS) to assist me in the challenges around simplifying complexity. In fact, I have a whole section on Hiding Complexity through various techniques in my Simplifying Complexity series.
Nice try, but still short
I wish my shift in mindset from having a “solution to document” to seeing a “documentation problem to solve” would be all that’s needed to move back into the more creative realm of critical inquiry (where I’m asking why questions and exploring theory and ideas). Unfortunately, the problem is more complicated (which I admit is a conclusion I’m almost predetermined to make).
Regardless of the amount of critical inquiry I might expend, the value of this critical inquiry will likely be overlooked. If overlooked, my workplace will not likely grant me the time or resources to engage in the critical inquiry.
In the most recent issue of Communication Design Quarterly, Jennifer Mallette and Megan Gehrke have an interesting article called “Theory to Practice: Negotiating Expertise for New Technical Communicators.” The article focuses on the experience of “Megan” (who is both a former student and also co-author). The gist of the article is that Megan’s training in Boise’s Master of Arts in Technical Communication program led her to believe that her expertise in tech comm would be valued in the workplace in the same way that engineers are valued for their expertise. She thought exchanges between tech writers and engineers would be made from a position of equality, where Megan’s decisions and recommendations about content and communication would be valued and acted upon in the same way as engineers’ decisions and recommendations. After all, this is how she was treated as a budding technical writer in the program. Different types of SMEs, that’s all.
Unfortunately, she found that wasn’t the case in the workplace. Instead, she was a second-class citizen. “Subject matter expertise” was a status not available for tech writers, who were basically secretaries or scribes in the organization. Anyone could challenge or dismiss the technical writer’s decisions about content, as the product owner or engineer ultimately owned the content and carried the authority. Megan had to frequently argue for the rationale behind her decisions, often presenting competitor’s documentation to show similar approaches.
The authors explain:
In some instances, no matter how a technical communicator works to build up credibility and SME status, product owners and SMEs can quickly override a recommendation. Although frustrating, Megan recognizes that the most she can do in these instances is assert her reasons for revisions, reference any available data, and state that she isn’t aligned with the decision as a way to continue to assert her expertise.
This “power hierarchy,” where “where communicators are viewed as support or secondary,” is somewhat pervasive in the profession. It seems that very few engineers and PMs are willing to respect tech writers as a SME.
Additionally, Megan found that in the workplace, rather than taking more active, lead roles in content creation (such as partnering on prototype design), technical writers played more passive, secondary roles — “receiving” and “waiting” on information from SMEs. The authors point to other research that finds similar experiences in the workplace. Research from Miles Kimball in 2015 also found that “technical communicators are limited to roles as scribes or ‘a matter of writing down things other people say, rather than of being involved in more strategic decisions about product development’” (qtd. in Mallete and Gerke). (Kimball’s research size was small (just 6 people), but they were part of STC’s Advisory Council, so presumably they were informative participants.)
So basically, even if you value solving documentation problems, others in the workplace will still treat you as a scribe, and consider that you’re performing a low-value task almost on par with the janitor’s changing of your trash can — something that surely must be done, but which is not by any means a task that would require a creative, intellectually engaged mind or other inquisitive focus. And you certainly don’t need more than one janitor to empty all the trash cans in the building.
That tech writers suffer from questions of value in the workplace is nothing new. And coming back to my original angst, why should I care whether outsiders to tech comm value the intellectual activity behind documentation? Couldn’t I just geek out on the rhetorical options and decisions around information design, content architecture, and structure to my heart’s content? My creative energy will find a home, so what do I care if others dismiss my work as trivial secretarial labor? I’m not looking for pats on the back and spotlight moments at all-hands meetings.
But there is a cost to devaluation of any activity in the workplace. If tech writing isn’t a challenging task, then why do you need so many tech writers? Couldn’t you get by with just two tech writers for an IT group of more than 800 engineers? As such, you may find yourself constantly under pressure to push out content, like the employees at In-n-Out who are rapidly compiling orders for an endless line of hungry people and cars. So even though I might not care how others value my task and role, that devaluation will likely impact me.
Making the intellectual work visible
What will help tech writers establish value in the workplace? As I said, this is a longstanding question in the tech comm profession, with no conclusive answers. But I do think there are some productive directions to consider.
In “Articulating Value Amid Persistent Misconceptions About Technical and Professional Communication in the Workplace,” Emily January Petersen argues that “the expertise of practitioners may be unknown to colleagues. Technical communicators must make that visible.” Much more could be said, but this is the essence of how to increase value: make visible the intellectual work you are doing.
If there was ever a story behind my blogging success, it’s this — I make my knowledge visible through my blog. Not for a second do I believe that I’m smarter or more experienced or more knowledgeable than 90% of people out there in the tech comm community, but stack me next to anyone for a job, and most of the time employers are won over by my blog. My blog makes my knowledge visible. It makes me visible.
How then do I take this same technique for visibility (and value) and apply it to the workplace? Without overthinking things here, I could write about my critical/analytical dilemmas and decisions and share that with those around me that I want to influence. Maybe it’s a newsletter, or an email list where there’s lots of chatter, or even an internal corporate blog. It shouldn’t matter as long as I take the time to articulate what I’m doing/thinking/trying.
There might be other solutions, and maybe my background as a blogger/writer makes me see writing and blogs as a solution to every problem, but why wouldn’t it work?
Conclusion
In this profession of technical communication, there are many times where I feel my greatest challenge is in learning the technology. It’s easy to forget that my role is not merely dictation and transcription or being a kind of secretary for engineers. My role is to figure out how to communicate the complexity in the best possible way, why we should take a certain rhetorical approach rather than some other.
As long as I keep focused on the challenges and difficulties in solving documentation problems (rather than just documenting the technical solution), my creative mind won’t feel suffocated. And as long as I constantly articulate, to my workplace colleagues, the intellectual journeys that I’m pursuing (as I deliberate about rhetorical decisions, user experiences, and solutions to documentation problems), I’ll hopefully maintain the value and status I need in the workplace to continue with the needed bandwidth and resources in this direction.
Short feedback survey on this post
Would you like to take a short survey to provide your input on the ideas in this post? If so, you can take the survey here. Thanks!
You can see the survey responses (so far) here.
References
Kimball, Miles A. “Training and Education: Technical Communication Managers Speak Out.” Technical Communication. Volume 62, Number 2, May 2015.
Mallette, Jennifer and Gehrke, Megan. “Theory to Practice: Negotiating Expertise for New Technical Communicators.” Communication Design Quarterly 6.3. 2018.
Petersen, Emily January. “Articulating Value Amid Persistent Misconceptions About Technical and Professional Communication in the Workplace.” Technical Communication Journal. Volume 64, Number 3, August 2017.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.