Upgrade to Pro — share decks privately, control downloads, hide ads and more …

How to write technical documentation that will save your career

Carmen Chung
February 21, 2020

How to write technical documentation that will save your career

Talk given at RubyConfAU2020 in Melbourne, Australia.

In this presentation, ex-corporate lawyer, Carmen Chung, will give you her top tips for writing tech documentation that people (including yourself!) will come back to, time and time again. Docs that are easy to understand, well structured, and a little bit fun.

Carmen Chung

February 21, 2020
Tweet

More Decks by Carmen Chung

Other Decks in Programming

Transcript

  1. Carmen Chung
    How to write tech documentation
    that will save your career
    !
    @carmenhchung

    View full-size slide

  2. ✅ Make your title “SEO” friendly.
    Write clear, precise and relevant
    titles.
    e.g. “How To Remove Columns From Our
    Database”
    ❌ But that doesn’t mean clickbait
    titles!
    e.g. “4 ways to remove columns from our
    database...the final one will shock you!”
    Tip #1: Pick your title carefully.
    @carmenhchung

    View full-size slide

  3. ✅ Have an index.
    - Make it clickable.
    ✅ Offer an introduction.
    - Explain what this document is going to do.
    - Mention required pre-reading.
    - Add TL;DR section if needed.
    ✅ Break up text.
    - Structure the document in easy-to-digest
    chunks.
    - Use screenshots, flowcharts, and diagrams.
    - Consider extracting information.
    Tip #2: Provide clear structure.
    @carmenhchung

    View full-size slide

  4. @carmenhchung

    View full-size slide

  5. ✅ Make updating docs part of the
    process.
    - Add it to your pre-deploy checklist.
    ✅ Give context with dates.
    e.g. As of January 2019, the process for removing
    columns from our database is this…
    ⚠ [Update] As of September 2019, we have
    moved towards a “strong migrations” approach
    for removing database columns…
    ❌ Don’t leave updating to others!
    Tip #3: Update regularly.
    @carmenhchung

    View full-size slide

  6. @carmenhchung

    View full-size slide

  7. ✅ Format code…and explain what it
    does.
    e.g. “Run pip install big-tech-co-repo in Terminal,
    which will install our entire repository on your
    machine in the current folder you’re in.”
    ❌ Don’t include secrets.
    e.g. “Run the create-database command in
    Terminal and it will generate the credentials for
    you, which will look something along the lines of
    (but be different to) this:
    1.URL: “https://big-tech-co.com/our-database”
    2.Username: “dummy-database”
    3.Password: “dummy-password”
    Tip #4: Make the most of code examples.
    @carmenhchung

    View full-size slide

  8. ✅ Selectively commit short, clear
    commit messages.
    ❌ “WIP WIP WIP WIP WIP”
    ❌ “Please just pass for once.”
    ❌ “WHY YOU NO PASS!”

    ✅ Add detail to your PR description.
    - Have a Pull Request template that is
    automatically applied to every pull request
    that is opened.
    Tip #5: Refine commit messages and PRs.
    @carmenhchung

    View full-size slide

  9. @carmenhchung

    View full-size slide

  10. ✅ Comment code when it needs
    context.
    - e.g. Something is not done for a reason or
    something is done that seems out of the
    ordinary.
    ✅ Add TODOs if you will do…
    - Mention who is to do what, why they’re to do
    it, and when they’re to do it.
    ❌ Don’t just comment code
    because it’s difficult.
    Tip #6: Comment code where necessary.
    @carmenhchung

    View full-size slide

  11. ✅ Cover all scenarios with context
    blocks.
    e.g.
    - When an account doesn’t have a user.
    - When an account has a user but the user has
    not yet selected their tier.
    - When an account has a user and the user is on
    a free tier.
    - When an account has a user and the user is on
    a paid tier.
    Tip #7: Write comprehensive specs.
    @carmenhchung

    View full-size slide

  12. Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    ✅ Write with precision and detail.
    - Who is to do what, by when, and why and how
    are they going to do it.

    View full-size slide

  13. Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    e.g. @DonaldTroll will create two pricing tiers
    today: one called “Free User” and one called
    “Paid User”.
    ✅ Write with precision and detail.
    - Who is to do what, by when, and why and how
    are they going to do it.

    View full-size slide

  14. Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    ✅ Be specific about tasks.
    - List actual attributes that need to be created.

    View full-size slide

  15. Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    e.g. The paid tier lets you:
    - read, create, update and destroy records.
    The free tier lets you:
    - only read records.
    ✅ Be specific about tasks.
    - List actual attributes that need to be created.

    View full-size slide

  16. Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    ✅ Keep a paper trail of all requests.
    - Tag people.

    View full-size slide

  17. e.g. I spoke to @FrancoPM about this today (1
    May 2019). He told me that as we have now
    finished the investor demo, we should turn off
    all the pricing tiers for now. I have done this.
    Don’t forget to re-activate this when we go live
    by setting the boolean “active” flag to true.
    Tip #8: Cover the 4 Ws + How.
    @carmenhchung
    ✅ Keep a paper trail of all requests.
    - Tag people.

    View full-size slide

  18. Conclusion
    !
    1. Pick your title carefully. ✅
    2. Provide clear structure.
    3. Update regularly. ✅
    4. Make the most of code examples. ✅
    5. Refine commit messages and PRs. ✅
    6. Comment code where necessary. ✅
    7. Write comprehensive specs. ✅
    8. Cover the 4 Ws + How. ✅ @carmenhchung

    View full-size slide