Some good decisions and minor mistakes
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.
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.
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.