$30 off During Our Annual Pro Sale. View Details »

Technical documentation is a backup (so make sure it works)

Peter Hilton
February 25, 2020

Technical documentation is a backup (so make sure it works)

Imagine working on a team of programmers who write perfect code, never forget anything, never leave the team, have perfect verbal communication skills, and love meetings. That would be weird on many levels, but at least then you’d have a chance of not needing any technical documentation. The rest of us, who have legacy code to deal with, need to know how to write useful documentation. Otherwise, other peoples’ code will become a single point of failure to understand what’s going on.

Technical documentation is our backup for not being able to understand a system and its code by looking at it. Unfortunately, these backups probably haven’t been tested recently and don’t actually work. The solution is to write less documentation, not more, but also not none. By writing less documentation, you can focus on writing documentation that counts, actually maintaining what you write, and have more time left over for writing code.

Peter Hilton

February 25, 2020
Tweet

More Decks by Peter Hilton

Other Decks in Programming

Transcript

  1. @PeterHilton
    http://hilton.org.uk/
    Technical documentation
    is a back-up
    (so make sure it works)

    View Slide

  2. View Slide

  3. Sergio Souza

    View Slide

  4. Ramon Cordeiro

    View Slide

  5. Three kinds of legacy code

    Good code
    but…
    old technology

    Code written by…
    someone else
    (a.k.a. bad code)

    Complex code
    because of…
    10 years’ built-up
    business rules
    6
    @PeterHilton •

    View Slide

  6. Three kinds of technical documentation

    Extensive tech
    documentation.
    Quality system
    records, e.g.
    code review forms
    No documentation
    at all. None.
    (not even code
    comments )

    Minimal docs:
    data dictionary,
    operations guides
    (and code
    comments )
    7
    @PeterHilton •

    View Slide

  7. Three lessons learned

    Generous budget
    Documentation
    was a backup

    Bad code, original
    team not available
    No backup was a
    problem.

    Planning for
    maintainability
    Minimum viable
    docs FTW!
    8
    @PeterHilton •

    View Slide

  8. Lessons learned

    View Slide

  9. We don’t like software documentation when it’s:
    1. Time-consuming
    2. Hard
    3. Wrong
    4. Messy
    5. Too long
    6. Missing
    7. Unversioned
    8. Incomplete
    9. Neglected
    10. Boring
    10
    @PeterHilton •
    Technical documentation has many failure modes
    … but no automated tests.

    View Slide

  10. ‘There is no documentation fairy’
    Allan Kelly
    Anthony Tran

    View Slide

  11. Technical design docs don’t help maintainers
    12
    @PeterHilton •
    Software design
    (a.k.a. development)

    ‘Technical specifications’
    =
    design choices and plans
    Maintenance
    (a.k.a. development)

    ? ? ?
    =
    how to understand
    and modify the code

    View Slide

  12. Three rules for backups
    Rule 1
    You need backups
    for important
    things
    (things go wrong)
    Rule 2
    Not using backups
    regularly might be
    a sign that things
    are going well
    (but also a risk)
    Rule 3
    If you haven’t
    tested your
    backups then they
    don’t work
    (things go wrong)
    13
    @PeterHilton •

    View Slide

  13. Three rules for documenting legacy systems
    14
    @PeterHilton •
    I had to invent a word for legacy systems…

    View Slide

  14. View Slide

  15. Three rules for documenting legacy systems
    Rule 1
    Bad code:
    needs all the docs
    you can get
    (like clues in a
    murder mystery)
    Rule 2
    There’s always
    too much code
    (so focus on
    getting started)
    Rule 3
    Some legacy
    systems are
    undocumentable
    (document the
    process instead)
    16
    @PeterHilton •

    View Slide

  16. How to cheat at docs

    View Slide

  17. How far will you go?
    Chris Moore

    View Slide

  18. How far will you go?
    You don’t have to write
    docs if you leave your
    mobile phone number
    in every source file.
    19
    @PeterHilton •

    View Slide

  19. Improve the code instead

    Better naming and
    cleaner code
    (fewer code
    comments)

    Automated builds
    (shorter
    installation
    instructions)

    Standard
    architectures
    (no system
    diagrams)
    20
    @PeterHilton •

    View Slide

  20. The ideal documentation system
    1. Works with your favourite IDE
    2. Integrated with source code
    3. Structured content
    4. Version control
    5. Minimal dependencies
    6. Doesn’t require writing one yourself
    when you should be working
    21
    @PeterHilton •

    View Slide

  21. Dejdżer / Digga / CC BY-SA 2.0

    View Slide

  22. Code comments
    Comments feature in almost all programming languages,
    but remain an almost taboo topic.
    Developers will go to bizarre lengths to avoid comments
    and usually fail to write code so good they don’t need any.
    Comments are not the enemy:
    meetings are the enemy!
    23
    @PeterHilton •

    View Slide

  23. How to write good code comments
    1. Try to write good code first.
    2. Write a one-sentence comment.
    3. Refactor the code (make it easier to understand).
    4. Delete unnecessary comments.
    5. Rewrite bad comments
    (all good writing requires rewriting)
    6. Add detail where needed.
    7. GOTO 1 24
    @PeterHilton •

    View Slide

  24. M A N N I N G
    Peter Hilton
    Erik Bakker
    Francisco Canedo
    FOREWORD BY James Ward
    Covers Play 2
    Play for Scala
    (Manning, 2014)
    Peter Hilton
    Erik Bakker
    Francisco Canedo
    http://bit.ly/playscala2p

    View Slide

  25. OPD
    OTHER PEOPLE’S DOCUMENTATION

    View Slide

  26. View Slide

  27. Use standards and frameworks
    Standards/dictionaries are other peoples’ documentation.
    Frameworks are other people’s code
    and the successful ones have good documentation.
    Not a perfect solution, because standards and frameworks
    are dependencies that you might not want.
    28
    @PeterHilton •

    View Slide

  28. MVD
    MINIMUM VIABLE DOCUMENTATION

    View Slide

  29. README.md
    The minimal system is a README per component,
    the short version of complete system documentation:
    30
    @PeterHilton •
    1. What it is
    2. Purpose
    3. Features
    4. Usage/examples
    5. Installation
    6. Asking questions
    7. Building from source
    8. Authors/maintainers
    9. How it works
    10. Who it’s for

    View Slide

  30. Special-purpose documentation for specific needs
    There are many kinds of documentation that you usually
    don’t need. But sometimes you do.
    31
    @PeterHilton •
    API reference
    Architecture diagram
    Contributor’s guide
    UML diagram
    Component inventory
    Entity relationship diagram
    Data dictionary
    Process model
    Business rules
    Architecture Decision Record

    View Slide

  31. You X Ventures
    Hire technical writers

    View Slide

  32. Docs as Code (Eric Holscher)
    1. Use the same tools for docs that you use for code:
    issue tracker, version control, mark-up, review, tests, etc.
    2. Use the development team’s workflows.
    3. Integrate docs development with the product team.
    4. Adopt shared ownership of documentation.
    5. Allow any team member to write the first draft.
    (Relevant for user documentation as well as system docs)
    http://www.writethedocs.org/guide/docs-as-code/ 33
    @PeterHilton •

    View Slide

  33. Documentation
    techniques wish list

    View Slide

  34. Architecture Decision Records (Michael Nygard)
    1. Concisely record each architecturally significant decision.
    2. Use sequential numbering and consistent titles, e.g.
    ‘ADR 1: Deployment on Ruby on Rails 3.0.10’
    3. Document context, decision, status, and consequences.
    4. Write-once: add new records to replace old ones.
    5. Read all records to ‘load’ the current state
    (it’s like event sourcing for documentation)
    http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions 35
    @PeterHilton •

    View Slide

  35. Four kinds of documentation (Daniele Procida)
    ‘There isn’t one thing called documentation, there are four’
    1. Tutorials
    2. How-to guides
    3. Explanation
    4. Technical reference
    ‘… each of these kinds of documentation has only one job’
    (it’s like design patterns for documentation)
    https://www.divio.com/blog/documentation/ 36
    @PeterHilton •

    View Slide

  36. A manifesto for error reporting (David R. MacIver)
    ‘a manifesto for how errors should be reported
    by software to technical people whose
    responsibility it is to work with said software’
    https://www.drmaciver.com/2013/03/a-rewritten-manifesto-for-error-reporting/ 37
    @PeterHilton •

    View Slide

  37. Summary

    View Slide

  38. Technical documentation
    1. Technical documentation is a backup for knowledge
    (and the rules for backups apply)
    2. We need technical system documentation,
    (but we don’t usually need very much)
    3. There are many new practices to replace old approaches;
    these practices have principles in common.
    39
    @PeterHilton •

    View Slide

  39. Technical documentation
    Technical
    documentation is
    a backup for the
    team’s knowledge
    (and the rules for
    backups apply)
    For maintenance,
    we need technical
    system
    documentation
    (but we usually
    don’t need very
    much)
    There are many
    new practices to
    replace old
    approaches
    (these practices
    have principles in
    common)
    40
    @PeterHilton •

    View Slide

  40. @PeterHilton
    http://hilton.org.uk/
    How to write maintainable code (training course)
    Documentation for developers (training course)
    more like this…

    View Slide