Tom Johnson, Senior Technical Programmer Writer at Amazon joins us in this episode of Knowledgebase Ninjas to talk about his technical documentation experience.

Connect with Tom and Amazon here:

• Tom Johnson
• Amazon

Key Takeaways:

How did Tom get into technical documentation?

Tom majored in English and achieved a masters in creative writing… he then moved into teaching writing at the American University Of Cairo and then became a marketing copywriter at a relatively low salary.

Tom then steered into technical writing quite simply because it paid well. He had previously resisted moving over as he thought it would be boring but after time, he realized that was far from the truth!

Tom’s team at Amazon has just two writers

Though the developer relations group that Tom is a part of is cross functional and includes development and marketing resources. Tom enjoys being part of small team as it’s easier to make decisions on the fly and get things done faster.

Tom’s documentation process

Tom and his team follow an agile documentation process which aligns with the development team. They work in two week sprints and share results at the end of each period.

Tom’s team also follow a specific five step review process. This starts internally:

• Internal review
• Product team review
• Field and support engineer review
• Legal review
• Beta partner review

Moving content through this process normally produces a very robust output.

Tom’s thoughts on “Docs As Code”

Tom defines the “Docs As Code ” process as following these five characteristics:

• Uses markdown
• Deployed with Git
• Continuous deployment method
• Test editor
• Compile through a static site generator

Tom completed a recent survey that found that 37% of people surveyed following this method. Tom enjoys this approach as it is very flexible…

That said, you may need a UX skillset in the team in order to deploy and would then have to add a custom search functionality which takes time and further investment.

Tom’s thought on the ROI of technical documentation…

Tom states that many documentation teams look too metrics to determine the value of their documentation.

One example of proposes that ROI can come from docs being used by the support team or customers… Tom states that this has a number of challenges:

• How do you measure many people read the docs but never contacted the support team?
• How do support agents know if they are solving support tickets with knowledge they gained from docs?
• How do you measure the amount of customers that rejected your project based on documentation?
• How do you quantify the value of any new business driven by docs?
• How do you measure the reduction in ramp up time of new employees?

It’s due to these reasons that when “people do math” to measure the ROI on technical documentation, Tom doesn’t find it very persuasive.

Who has inspired Tom in technical writing?

• Mark Baker – Author of Every Page is Page One and Structured Writing: Rhetoric and Process

Resources mentioned:

• I’d Rather Be Writing – Tom Johnson
• Value arguments for docs and tech comm (Part II): Reviewing past research – Tom Johnson
• Value arguments for docs and tech comm (Part III): Determining value through usage – Tom Johnson
• Limits to the idea of treating docs as code – Tom Johnson
• “Value from perceptions from others” (Saul Carliner reference) – Saul Carliner
• “Value from knowledge creation” (Mike Hughes reference) – Mike Hughes
• “Every Page Is Page One” – Mark Baker
• Descript Help Center
• Cave of Programming
• Docs-as-code tools

Subscribe To Knowledgebase Ninjas:

• iTunes
• Spotify