Since I created this blog (almost eleven years ago), I've been writing about nearly every role related to building software. But there's one I've barely mentioned so far - Technical Writer. It's an oversight I'd like to fix today - let's talk about who they are, what they do, and when you should realize you need one.

Let's start with basic facts:

  • writing is an important skill - a skill that requires a lot of deliberate practice
  • writing well is not easy - but writing poorly (and mindlessly, w/o cont. improvement loop) is, in fact, even worse than not writing at all (as it wastes time)
  • the majority of developers do not like writing (texts, they are OK with code, obviously)
  • very few of the ones in charge push developers to write - they could rage-quit, and besides: they are too expensive for such a mundane, "non-value-creating" job
  • while at the same time, 95% of software building companies suck big time when it comes to knowledge management - written information is outdated, knowledge is siloed, not protected against individuals' departure, and affected by the cognitive load limitations

So, following the old corporate rule: if we have a problem with X, why don't we create an "X manager/handler" role? :) Let's hire someone to do the writing work for us.

It's specific

But not ANY writing - the technical writing, which is:

  1. structured nearly to a level that allows automated validation
  2. peppered with elements of several visual notations (more or less formal ones)
  3. concise, without repetitions, easy to navigate (e.g., to search through), and modify (adjust to ever-changing reality)
  4. crystal-clear when it comes to vocabulary: ubiquitous language instead of expressive synonyms and metaphors
  5. relentless (but also creative) in pursuit of (merciless) deprecating or updating whatever has lost its accuracy (and/or value)
  6. highly iterative - nothing is ever fully done, it's just up-to-date or not really
  7. requires a proper "sense of balance" - where the details are necessary and where they just obscure the picture

In the end, apart from all the abstract thinking and ability to express one's thoughts, to be a Tech Writer one needs a certain level of understanding of the tech (which is being documented). Good Tech Writers invent and adjust the form of writing to the problem being described/documented.

According to many, the best documents are hybrid - at least partially generated automatically (e.g., based on the code/database structure or workflow definition). The human touch is supposed to bring in more context, fill the information gaps, and make the content more comprehensible and approachable. Mixing these two approaches (effectively) is a skill as well.

Having a single person (or even a small group) in a constant chase to catch up with galloping development doesn't sound realistic (especially mid-/long-term). It sounds cruel :) But fortunately, it doesn't have to look like that.

Technical Writer may in fact:

  1. act as a writing coach/reviewer for others (who are obliged to produce certain deliverables, e.g., as part of their Definition of Done)
  2. facilitate/coordinate the joint efforts to build common (reasonable) templates, standards, and conventions
  3. focus on the coherent, comprehensible general structure of the knowledge base (to provide others places to "hook into")
  4. take ownership over the key (most important, most visible/impactful) artifacts - to serve as an example - a reference point for others

Yet still, I know very few organizations that have hired a Technical Writer (even among those who have technical products available for the external audience - e.g. APIs/SDKs). I can only speculate about the reasons:

  • some are too small to recognize the need at this point (obviously)
  • some believe that the only reasonable documentation is "self-explanatory code"
  • some are adamant about documentation being an integral part of the product - hence it's the teams' responsibility to tackle that topic
  • many prefer sticking to non-technical docs - like functional requirements/specifications and/or UI design
  • people who haven't seen that role in action (and the positive outcomes it can bring) may not even be aware it exists :)

Are they for real?

Truth be told, this IS a niche role. Search through your professional network (e.g., on LinkedIn) - how many Technical Writers do you know? It is not a typical career in tech: how did they end up being one?

That is probably the trickiest part - there's no "typical" Technical Writer career path. No primer on how to become one (or how to recognize a suitable talent and train them). No written (no pun intended) Body of Knowledge. If you'd like to acquire one, you need to get creative - both regarding the search and the actual recruitment process (skill evaluation, seniority assessment, etc.). The same applies to evaluating one's performance - there's not a single good answer on how to measure the effectiveness of a Technical Writer.

What about you?

So, how about you and your experience with Technical Writers?

  1. Did you hire one / do you plan to do that shortly?
  2. Did you bring in the experienced hire or drill someone from scratch / retrain someone who already was in a similar role? (e.g. a business analyst)
  3. What was the main driver behind the decision to hire the Tech Writer?
  4. What's the area of accountability/ownership of your Tech Writer(s)? E.g. do they create tutorials or code samples as well?
  5. What are their mutual obligations to the (product/development) Teams?
  6. Do they measure/estimate the "Doc Debt"?
  7. Do you "use" Tech Writers to produce externally visible artifacts only (e.g., API/SDK/user documentation)? Or do they also participate in internal activities (e.g., creating ADRs, maintaining the logical design, and documenting the technical decision process)?

All the input is highly appreciated - please use comments to share your experience/opinions.

Share this post