✨ 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
Top comments (0)