Talk Talk: 'One AWS team’s move to docs as code: what worked, what didn’t, what’s next' (Write the Docs 2022)

✨ What is this post about: As a part of my professional growth, I make time to watch conference talks on Ruby, Rails, JS, React, tech writing, and tech trivia. Previously, I'd just watch them but now I will take and publish notes for future reference.

✨ Talk: 'One AWS team’s move to docs as code: what worked, what didn’t, what’s next' by Marcia Riefer Johnston and Dave May

✨ One-paragraph summary: A talk that portrays the journey that the AWS took to switch from authoring the docs in Word (until 2020) to the 'docs-as-code' approach.

✨ Impression: Very fascinating journey in time.

Table of contents

• Notes
• Read more

Notes

• talk about implementing the collaborative process of doc authoring (or docs-as-code)
• "Docs as code" - treat documentation the way you treat code:
  • version control
  • doc artifacts automatically
  • trusted set of reviewers
• Previous process (publishing in Word until 2020)
  • engineer built the software (quickstart)
  • engineer created a doc in word
  • tech writer edited it
  • both collaborated in email (back and forth)
  • tedious
  • problematic versioning of Word
  • publishing to pdf
• New process (docs-as-code)
  • engineer built the software (quickstart)
  • engineer created a doc in AsciiDoc in VSCode
  • "it feels like a step back because it's lacking WYSIWYG"
  • no worries about formatting, about fonts or margins
  • tech writer edited it in AsciiDoc in VSCode
  • both collaborated in github
  • transparency in history
  • less tedious
  • open source
  • easier for pull requests, editing
  • all changes are tracked
  • all changes are published automatically
  • published to GitHub pages
  • automatically (script and cascading stylesheets)
• Automation! A game changer in:
  • GitHub page creation
  • formatting
  • version history tracking
• Initial pains
  • unneeded code tests delayed publishing (a typo fix can take hours because of the end-to-end testing process)
  • repetitive content is a pain to maintain if it changes (retroactively, manually)
  • doc process got confusing for authors
• Outcome
  • moving from Word to docs-as-code reduced the time from publishing time by 25% (and then after improvements by further 50%)
• Next steps
  • dependency on CI/CD developers on debugging
  • automate doc testing, linting
  • adding version control to boilerplate updates
  • adding more doctyped & code variants
  • managing translations

Read more

• Docs as code: