DEV Community

Sylwia Vargas
Sylwia Vargas

Posted on

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

  • 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

Top comments (0)