The Fourth Amigo

A couple of things converged in the last week that has finally prompted me to put these thoughts together.

The first was preparing for a company-internal AMA I’m doing about building / supporting the creation of a “shifted-left” embedded test organisation. The second was a sequence of tweets about the threshold of value of seemingly minor observed defects, one example being typos in the UI / documentation.

The thoughts centre around the relative position of the technical author role in a company, and how testers can and should develop a close working relationship with them where possible.


From working closely with technical authors – admittedly, some time ago now – it’s apparent that there are (at least) a few similarities between how testers and technical authors operate;

  • they are often siloed off into specialist teams, struggle to get information about the product, and have their work squeezed by slipping code and unmoving deadlines
  • when embedded into development teams, they don’t necessarily get invited to all the meetings as a matter of course, resulting in them missing out on vital information
  • they initially base their work from requirements / user stories, have to learn and react to the ways the built software might be different, and document the result
  • they need software to be deployed and usable (to test systems) in order to produce their work products
  • they communicate how the software operates
  • they ask questions when the product doesn’t operate as expected.

Work Products

A tester’s primary job is to highlight where the software does not meet the expectations its users might have, in any of the many qualities that software provides to its users.

A technical author’s primary job is to document exactly how the software needs to be used to meet the expectations its users might have, in any of the many qualities that software provides to its users.

(One of) A tester’s primary work product is a list of the ways the product doesn’t meet one or more expectations. A technical authors primary work product is a list of ways the product does meet one or more expectations, and specifically how it can meet them.

These are very similar processes resulting in not dissimilar outputs, albeit with different target audiences (bugs wholly internal, docs largely external);

  • test scripts – either (shudder) manual or automated – are effectively a documented path through some features of the software, with things to do and see along the way. They are a document of how to interact with the product from a user workflow perspective.
  • product documents (there are many types, but I’m referring to user guides here) are a map of the software with instructions how to interact with the product on each new interface. They are a document of how to interact with the product from a product hierarchy perspective.

Both roles’ primary work products are records of the software behaviour from two different perspectives and expressed in slightly different ways.

Product Knowledge

In the nearly 15 years since I started trying to push testing left in my organisation, one of the main lessons was that “left” is not the only direction in which one can or should push. In an old post on the subject, I suggested a more accurate but less catchy maxim: “Expand Outwards”.

I think we can all see why that would never catch on. However, it does remind one to not just look left for activities and people with whom to foster closer working relationships. Look “right” and work with Customer Services; I’d argue no-one in your org knows the software, and the associated woes of customers, better.

Tying with testers for the broad product knowledge silver, I’d put technical authors. They literally wrote the (usually many) books on the product. They have documented how to interact with every control in every dark and dusty corner of the product. They have taken screenshots of every dialog.

Shifting Left

Given that testers and technical authors both produce similar work products and require wide and deep product knowledge, it’s logical to shift both roles “left”, not just testers.

If you’re in a meeting (or trying to get into meeting) where product information is being shared / created, bring your technical author colleague with you. The things that make testers’ jobs easier can also make a technical authors job easier.

It can initially be difficult to make the case for inclusion, as testers can be outwardly passive in these meetings (because they are actively listening / learning). However, it will not take long before a tester’s spidey sense starts tingling and they start asking questions that makes it clear there is not yet a good answer.

Technical authors can absolutely interact in the same way; actively listening and learning about upcoming features, as well as questioning and clarifying the implementation.

“The Fourth Amigo”

The term “three amigos” has been around for some time, typically referring to close working and information-sharing relationships between product managers, developers, and testers. It’s high time that technical authors are added to those conversations.

Technical Authors are a reliable source of product information who are professional communicators; they can clearly explain the often complex concepts built into the product. If they struggle to communicate a concept, that’s a smell the team should not ignore.

If they are able to engage in parallel with development and testing, Technical Authors are another vital source of information into, and perspective on, the development process. You owe it to them, yourself, your team and your customers to utilise their knowledge and communication prowess.