API docs have code snippets in them to help users get through simple and complex problems. Those code snippets are the ones most likely to be broken. In this talk, you’ll learn how to ensure that none of the code in your docs will be out of date & how you can make it part of your deploy cycle. When you’re focused on getting a bug release shipped, one of the last things you’re thinking about is updating the docs. So the docs get shipped and become out of date with the current version of your API. That’s when users start getting confused and it could take weeks to figure out it’s because they are copying an old example from your documentation. By including unit tests for all of the code snippets you use, you’re setting yourself up for long-term success with documentation maintenance. It’s no different than writing tests for the APIs and it will save you a lot of time trying to handle user questions. By the time attendees leave this talk, they will know how to implement unit testing into their new or existing docs and how they can deploy them.

1. Unit Testing Your Docs
Milecia McGregor @FlippedCoding
Developer Advocate @conductotech

2. Overview
Why Documentation Matters
Code Snippets in Docs
Example Doc Application
Writing Unit Tests for Snippets
Including Doc Tests in CI/CD
Key Takeaways

3. Why Documentation Matters
Helps external developers figure out what to do
Helps internal developers figure out what’s happening
Gives tech leaders an idea of if they want to use your tool
Gives marketing something to work off of
Helps make your tool look more authoritative

4. Code Snippets in Docs
Shows off how to use your tool
What developers are looking for most of the time
Expected to work on copy-paste
Where you lose a lot of people

5. Example Doc
Application

6. Writing Unit Tests for Snippets
Write the code as a separate file and import it
No code blocks are written in the doc
Make sure configurable code is highlighted
It’s the same as unit testing your application code

7. Including Doc Tests in CI/CD
Include it in your build process
Run it in parallel so it doesn’t stop the main run
Fix the bugs when you see them
Use this automation to make docs
easier to maintain

8. CI/CD Example

9. Key Takeaways
Code snippets in docs are just as important as the code
No one can use your APIs without good documentation
It’s not too much extra work
You’ll stop a lot of confusion