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.

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