TDD: Test-Driven Documentation
![](https://s3.amazonaws.com/media-p.slid.es/uploads/1098231/images/6391725/gleb-alternative.jpg)
Gleb Bahmutov
Distinguished Engineer
Cypress.io
@bahmutov
our planet is in imminent danger
https://lizkeogh.com/2019/07/02/off-the-charts/
+3 degrees Celsius will be the end.
survival is possible* but we need to act now
- change your life
- quit fossil fuel bank
- join an organization
AGENDA
-
Horses, bicycles, and cars
-
Types of docs and common mistakes
-
Tested Markdown
-
Tests as docs for your apps
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370135/pasted-from-clipboard.png)
If all you know is
🏇
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370142/Screen_Shot_2021-03-21_at_9.03.54_AM.png)
😲
😐
🤮
😳
🤔
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370152/pasted-from-clipboard.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370298/pasted-from-clipboard.png)
State of the art "technology" - the horse
the bicycle
// WHY DOESN'T THIS WORK!!?
const text = await cy.get('#inner').text
expect(text).to.equal('Submit')
cy.get('#inner')
.should('have.text', 'Submit')
Why?!!! How is this better?!!!
cy.get('#inner')
.should('have.text', 'Submit')
.and('have.css', 'color', 'rgb(255, 0, 0)')
.click()
Makes the tests human
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370142/Screen_Shot_2021-03-21_at_9.03.54_AM.png)
Build a successful business at each step of the journey
👶
👦
😁
🤘📢
👩🧑🧔
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370142/Screen_Shot_2021-03-21_at_9.03.54_AM.png)
Full set of training, documentation, materials
📚
📚
📚
📚
📚
📚
📚
📚
📚
A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over, beginning with a working simple system.
- John Gall
A complex system that works is invariably found to have evolved from a simple well-documented system that worked.
"Gleb's Law"
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8370142/Screen_Shot_2021-03-21_at_9.03.54_AM.png)
👁
🥇
Fully lock yourself before attempting the next climb
Types of docs
-
Marketing copy
-
Guides
-
Reference
-
Tutorials and recipes
-
Example applications
-
Blog posts
-
Webinars
-
Conference talks
-
Comparisons to other tools
Problems with Marketing
Selling the drills and not the holes
Fast, easy and reliable testing for anything that runs in a browser.
Cross-platform e2e test runner
Problems with Guides 1/2
Tell me why I should read it
npm install ...
🙁
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374791/Screen_Shot_2021-03-22_at_12.04.52_PM.png)
Problems with Guides 2/2
Not stating the requirements clearly
This guide assumes you know X and have Y and Z
Open the app and ...
🤔
Problems with Reference Pages
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374825/Screen_Shot_2021-03-22_at_12.13.00_PM.png)
Problems with Reference Pages
- Lack of examples
- Examples out of date
- Examples are all "foo" and "bar"
- Non-uniform page structure
- Missing history
- Not linking to larger guides and tutorials
Problems with Reference Pages
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8384017/Screen_Shot_2021-03-24_at_9.25.37_AM.png)
Problems with Tutorials
- Tutorials are out of date
- Missing source code
- Missing CI
- Expectations not stated
This is how you drill a hole...
Problems with Blog posts
Missing the published date
When was this written?
Is this even relevant?
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374231/Screen_Shot_2021-03-22_at_9.46.14_AM.png)
Problems with Blog posts
Missing version numbers
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374298/Screen_Shot_2021-03-22_at_10.00.43_AM.png)
Problems with Blog posts
Missing version numbers
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374303/Screen_Shot_2021-03-22_at_10.01.29_AM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8374309/Screen_Shot_2021-03-22_at_10.02.32_AM.png)
Problems with Webinars and Conference Talks
- No links from the webinar to the rest of documentation
- No links from the rest of the documentation to the webinar or talk
- Index of the talk with direct links to the individual sections
- Scrapable and searchable
- Can be linked from other pages
📛 Obstacles to good documentation
-
Private code or project
-
Diffuse responsibility
-
Hard to maintain
📛 Often missing from the docs
Repetition: the common themes should be repeated through the documentation
💡Tip: Let People Learn More
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8375429/Screen_Shot_2021-03-22_at_3.03.57_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8375429/Screen_Shot_2021-03-22_at_3.03.57_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8375433/Screen_Shot_2021-03-22_at_3.04.19_PM.png)
💡Tip: Let People Learn More
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8375440/Screen_Shot_2021-03-22_at_3.07.06_PM.png)
💡Tip: Let People Learn More
💡Tip: Teach Users to Search
💡Tip: Teach Users to Search
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8381530/Screen_Shot_2021-03-23_at_9.49.03_PM.png)
Tests should be closer to their targets
Keeping Examples Correct and Up-to-date
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138703/Screen_Shot_2021-01-17_at_7.33.23_PM.png)
If I see a question on a forum, GitHub, Twitter, etc
How do I toggle a checkbox?
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138710/Screen_Shot_2021-01-17_at_7.32.26_PM.png)
App HTML
Test code
Markdown file
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138716/Screen_Shot_2021-01-17_at_7.32.41_PM.png)
Markdown file
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138710/Screen_Shot_2021-01-17_at_7.32.26_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8376587/Screen_Shot_2021-03-22_at_10.28.59_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8376589/Screen_Shot_2021-03-22_at_10.19.17_PM.png)
Markdown is king
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138717/Screen_Shot_2021-01-17_at_7.37.08_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138703/Screen_Shot_2021-01-17_at_7.33.23_PM.png)
Markdown spec also becomes a static docs page
Every example is scraped into the docs index
💡 Do NOT answer support questions
💡💡💡 Especially for private support
💡 Do NOT answer support questions
Instead, update the documentation, or create an example, or write a blog post.
Then answer with a link
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8138780/Screen_Shot_2021-01-17_at_8.01.01_PM.png)
💡 The Support Team
Should eliminate their own jobs by writing more and more documentation until the users find everything themselves
and double their salaries
Tutorials / recipes / example apps
- Do not let dependencies fall behind
- Communicate versions used
{
"extends": [
"config:base"
],
"automerge": true,
"masterIssue": true
}
renovate.json
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8376602/pasted-from-clipboard.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8383936/pasted-from-clipboard.png)
- A pull request is opened automatically based on the schedule
- If all tests pass, the PR is merged by RenovateBot
name: badges
# update README badge only if the README file changes
# or if the package.json file changes, or this file changes
on:
push:
branches:
- master
paths:
- README.md
- package.json
- .github/workflows/badges.yml
jobs:
build:
name: Badges
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎
uses: actions/checkout@v1
- name: Update version badges 🏷
run: |
npx -p dependency-version-badge update-badge cypress cypress-react-unit-test
# commit any changed files
# https://github.com/mikeal/publish-to-github-action
- name: Push any changes to repo 📤
uses: mikeal/publish-to-github-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
.github/workflows/badges.yml
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8376603/pasted-from-clipboard.png)
💡 Use Example Apps to Test New Releases
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8384931/pasted-from-clipboard.png)
"Testing" README.md
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8379906/Screen_Shot_2021-03-23_at_1.07.55_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8379914/Screen_Shot_2021-03-23_at_1.08.32_PM.png)
"Testing" README.md
- Install and use your library / app as if you were a novice user blindly following the README instructions
- Even better to have someone else do it for you
🖥 What About My Apps?
Create and embed app screenshots from tests into your documentation
🖥 What About My Apps?
Tests become the status of your project
🖥 Tests are Demos
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8381567/arrows-from-different-directions-movie.gif)
Document what you have
Now
Make writing correct documentation easy
You are not there with the user
But your documentation is.
![](https://s3.amazonaws.com/media-p.slid.es/uploads/22518/images/8381662/Screen_Shot_2021-03-23_at_9.40.45_PM.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/1098231/images/6391725/gleb-alternative.jpg)
Thank you 👏