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

Helping Future You with Internal Technical Documentation

Audrey Troutt
September 12, 2019

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.

Audrey Troutt

September 12, 2019
Tweet

More Decks by Audrey Troutt

Other Decks in Programming

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