Helping Future You with Internal Technical Documentation

I'd like to talk about internal technical documentation. Specifically, how to communicate technical ideas to other developers. I'll cover common diagrams like sequence diagrams, workflow diagrams, architecture diagrams, and UML/class diagrams, as well as provide guidelines for how much description vs diagrams vs API specs vs code comments you should make depending on the audience, time available, and complexity of the code being documented.

Transcript

1. HELPING FUTURE YOU:
   INTERNAL TECHNICAL
   DOCUMENTATION
   September 2019
   Audrey Troutt
   @auditty
   audreytroutt
   

   View Slide

2. WHY DOCUMENT CODE?
   

   View Slide

3. 3
   IF NO ONE
   KNOWS WHAT
   IT’S FOR,
   IT MIGHT AS
   WELL NOT EXIST
   

   View Slide

4. WHO IS THIS
   DOCUMENTATION FOR?
   

   View Slide

5. 5
   WHO IS THIS DOCUMENTATION FOR?
   THIS IS FOR OTHER DEVS THAT
   WILL WORK ON THIS CODE
   They need to be able to
   understand enough to run,
   change, test, build, and deliver
   new versions of this app.
   THIS IS FOR YOU AND YOUR
   TEAM
   If enough time passes this is
   the same as making
   documentation for other devs.
   ß
   Future you has forgotten
   everything!
   THIS IS FOR PEOPLE WHO
   AREN’T DEVS OR WHO WILL
   CONSUME BUT NOT UPDATE
   THIS CODE
   They need to understand what
   this is, how it works, and how
   to use it.
   

   View Slide

6. 6
   WHAT DOES YOUR READER ALREADY KNOW?
   • Can you assume they understand the language and platform at
   the same level as you?
   • Can you assume they have the specific domain knowledge
   needed?
   • Can you assume they are familiar with the product or app as a
   consumer?
   • Can you assume that you or someone familiar with the code will
   be around to help them?
   

   View Slide

7. 7
   •How the code works?
   •How to build, test, update, release it?
   •How to use the code?
   •Product knowledge?
   •Domain knowledge?
   WHAT DOES YOUR READER NEED TO KNOW?
   

   View Slide

8. HOW DO YOU DOCUMENT
   THIS INFORMATION?
   

   View Slide

9. 9
   README
   EVERY REPO SHOULD HAVE A README
   • What is this?
   • Where to start?
   

   View Slide

10. 1 0
    CODE COMMENTS
    SELF-DOCUMENTING CODE IS GREAT
    FAILING THAT, ADD A COMMENT
    Code comments are helpful for sharing
    information about your specific
    implementation, anything that isn’t
    going to be obvious to the reader.
    

    View Slide

11. 1 1
    API SPECIFICATION
    USING MARKDOWN YOU CAN TAKE A
    MORE FORMAL APPROACH TO CODE
    COMMENTS
    If you are creating a library or API for
    other developers to consume, it’s a
    good idea to fully document the API:
    classes, functions, parameters, return
    types, constants, etc.
    See https://nshipster.com/swift-
    documentation/ for great reference on
    Swift markdown documentation and
    Jazzy.
    

    View Slide

12. 1 2
    WIKIS AND DEVELOPER
    GUIDES
    WHEN A README ISN’T ENOUGH, IT’S
    TIME FOR A WIKI
    In-depth technical, domain, or product
    documentation is hard to cram into a
    README.
    You may need a search tool, navigable
    outline, and many explanations, code
    samples, images, diagrams, and links.
    

    View Slide

13. 1 3
    EXAMPLES
    IF A PICTURE IS WORTH A THOUSAND
    WORDS, THEN A WORKING EXAMPLE IS
    WORTH A MILLION
    If you are creating a library for other
    developers to consume, it’s a good idea
    to provide working examples or sample
    applications to help devs learn how to
    use it.
    

    View Slide

14. DIAGRAMS
    

    View Slide

15. 1 5
    ARCHITECTURE
    DIAGRAMS
    SHOWS THE OVERALL STRUCTURE OF A
    SYSTEM AND HOW THINGS ARE
    CONNECTED
    Architecture diagrams take many
    different forms and can cover whole
    systems or generic subsets of the app
    architecture, like this MVVM diagram
    from https://github.com/blkbrds/arch-
    mvvm-ios
    (very common)
    

    View Slide

16. 1 6
    DATA FLOW DIAGRAMS
    SHOW HOW DATA FLOWS THROUGH
    SYSTEMS OR PROCESSES
    This is for documenting where data
    comes from and how it is changed and
    stored.
    Example usage: explain how customer
    profile information is consumed,
    processed, used for segmentation,
    aggegated, and stored
    (common)
    

    View Slide

17. 1 7
    SEQUENCE DIAGRAMS
    SHOW THE SEQUENCE OF MESSAGES
    BETWEEN COMPONENTS OR SYSTEMS
    Components or systems are represented
    by vertical bars.
    Arrows across represent messages
    (requests and responses). The sequence
    of events happen from top to bottom.
    Usage example: explain how requests
    flow to multiple backend dependencies
    (mobile app, auth provider, data API,
    media API, back to mobile app)
    (common)
    

    View Slide

18. 1 8
    WORKFLOW DIAGRAM
    SHOWS THE PROCESS
    Processes include multiple steps with
    transformations or logical transitions in
    between.
    UML (unified modelling language) gives
    standard meaning for each of the
    shapes
    Usage example: explain a process for
    defect triage.
    (common)
    

    View Slide

19. 1 9
    CLASS DIAGRAM
    SHOW THE RESPONSIBILITIES AND
    RELATIONSHIPS BETWEEN CLASSES
    This example is a UML class diagram. It
    shows the functions and data on each
    class and how it relates to other classes.
    Example usage: code preview with your
    teammates before embarking on green
    field development
    (rare)
    

    View Slide

20. 2 0
    STATE DIAGRAMS
    SHOWS STATES OF A SYSTEM AND
    WHAT TRANSITIONS EXIST BETWEEN
    THEM
    A state diagram is useful for
    documenting stateful systems.
    Example usage: explain how a home
    security system might have several
    states: disarmed, arming, armed, alarm
    in progress, disarming, etc. You are only
    ever in one state at a time.
    (rare)
    

    View Slide

21. HOW MUCH TIME DO YOU
    HAVE?
    

    View Slide

22. View Slide

23. IF NOTHING ELSE
    

    View Slide

24. 2 4
    IF NO ONE
    KNOWS WHAT
    IT’S FOR,
    IT MIGHT AS
    WELL NOT EXIST
    

    View Slide

25. 2 5
    ALWAYS MAKE A
    (NON-EMPTY)
    README
    

    View Slide

26. Audrey Troutt
    @auditty
    audreytroutt
    

    View Slide

27. 2 7
    IMAGE CREDITS
    RESOURCES
    • Icons from Material design https://material.io/
    • Key Photo by Michael Dziedzic on Unsplash
    • Screenshot of
    https://github.com/CocoaLumberjack/CocoaLum
    berjack
    • Code comment screenshot from Fastlane
    https://github.com/fastlane/fastlane/blob/master
    /fastlane/swift/SocketClient.swift
    • Jazzy/Alamofire doc sample from
    https://github.com/realm/jazzy
    • RxSwift Example example from
    https://github.com/ReactiveX/RxSwift/blob/mast
    er/Documentation/ExampleApp.md
    • Wiki screenshot from Fastlane
    https://docs.fastlane.tools/
    • MVVM diagram from
    https://github.com/blkbrds/arch-mvvm-ios
    • Other diagrams created in Lucidchart from default
    templates
    • Welcome door photo by Taylor
    Simpson on Unsplash
    

    View Slide