Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 6,100+ subscribers. (See email archive here.)

Search results

Some good decisions and minor mistakes

by Tom Johnson on Feb 17, 2021 •
categories: technical-writing

During my transition time between Amazon and Google, I decided to create a brief list of some good decisions and minor mistakes during my five years at Amazon. This is a brief list, without much elaboration, but I think it's still valuable.

Good decisions

  • Getting embedded with product/engineering teams. Whenever I embed with engineering teams, life goes well as a tech writer. When I’m distanced from engineering teams, things take a turn for the worse. Basically, I get too disconnected from the source and flow of essential information.

  • Using an intake process that required a lot of info upfront information. Intake processes that put some information pain on the requester in turn make it easier as a tech writer because you have more of the information you need upfront. (See my process for large intake requests versus small intake requests.)

  • Sharing out updates to the wider group. Broadcasting all the recent doc updates made during the past month or so did an amazing job at increasing the visibility of our team. This had more impact than any doc-related metrics. For more details, see Status reports – a tool for visibility and relationship building.

  • Slack channel groups as a means of communication about docs. When the company adopted Slack and we started using channels for doc projects, it was a game-changer. Communication was so much easier, as people could easily tag others into the conversation.

  • Aligning doc efforts with the org’s strategic priorities. There’s a lot we could focus on, but when we wised up and started aligning our doc priorities with the department’s strategic priorities, that is, putting more focus on the projects that mattered to execs, our work took on more importance and recognition.

  • Aligning with DevRel groups to drive the doc focus. In addition to aligning strategically with the important projects in the org, aligning with the priorities of the DevRel group (also called solutions architects or partner engineers) helped us focus efforts in the right direction, since DevRel groups are closely tied with users.

  • Using workflow maps for complex processes. For lengthy processes, I used workflow maps to connect topics and received great feedback through this. I’m convinced that it’s the way to go when creating lengthy implementation processes. I wrote about this here: Principle 1: Let users switch between macro and micro views.

  • Embedding feedback forms directly below docs. We experimented with a few different ways of collecting feedback, but when we put a form embedded right below topics as an iframe, making it dead simple to communicate feedback, we started receiving a ton of comments. I wrote about this here: Processes for collecting feedback post-release.

  • Using an engineering workflow for doc work. When we adopted the same workflow for docs that engineers used in their teams (Scrum), engineers more readily understood our doc workflow and how we managed the work. It was also easier to plug into engineering workflows.

  • Setting a timer for four hours each day to write. When I started a four-hour timer to make sure I spent a good part of the day actually writing content, my productivity went way up. I wrote about this here: Writing productivity tip: Focus sessions.

  • Implementing Jekyll in a docs-as-code workflow. I was fortunate to arrive at a time when we were eager to transition tools, and we implemented Jekyll. I got to work on the theme, the publishing workflows, and other aspects of the docs-as-code solution. This was one of my major highlights, and I realized that I’m pretty good with tools. Looking back, this was a good solution, and it really allowed us to deliver content in more efficient ways. For more details, see Case study: Switching tools to docs-as-code.

Sponsored content

Minor mistakes

  • Getting loaned out to another group while still reporting in the same group. This was the dumbest mistake I ever made. If you’re in one group but get loaned out to another group, you basically end up creating docs for both groups. Instead of getting loaned out, you might as well transition teams in a more formal way because it makes no sense to do work for a group you don’t report into, even if your headcount gets re-allocated to that group.

  • Allowing contributors to commit without reviewing what they commit. We had an idea of scaling docs by allowing engineering teams to write and contribute docs in an autonomous way. I didn’t start closely examining some of their contributions until too late, and then I realized that we should have been more closely monitoring and reviewing their content.

  • Not aligning more closely with support groups. As mentioned earlier, we aligned with our DevRel teams to figure out what docs were the priority. The support team often interfaced with lower priority users (from a business standpoint). Their processes largely remained separate from ours in a way that we never fixed. There was always a chasm between docs and support, even when our teams merged under the same umbrella.

  • Not measuring progress in a quantifiable way. I tried a lot of different ways to track metrics, as I had 5 managers in 5 years and this topic (what to track and report on) always surfaced. No metrics ever really stuck. We shifted from tracking one thing to the next in ways that never seemed to catch the attention of leadership. The only reporting efforts that caught leadership’s attention were the broadcast emails about doc updates.

  • Not implementing more scripts to check doc health in automated ways. I spent a lot of time on tools, perhaps too much time. I developed extensive scripts to identify outdated content, but I never saw this approach through to the end. As a result, a lot of docs gradually went out of date without signaling any alarm bells.

That’s about it. I enjoyed my time at Amazon, just like I’ve enjoyed my time at every company I’ve worked at. Each company offers unique experiences, culture, people, tools, and challenges. What works well at one company might not work at another, but I hope to repeat what worked well and reduce the mistakes as I move forward.

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 6,100+ subscribers. (See email archive here.)

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.