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
2. WHY DOCUMENT CODE?
3. 3 IF NO ONE KNOWS WHAT IT’S FOR, IT MIGHT AS WELL NOT EXIST
4. WHO IS THIS DOCUMENTATION FOR?
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.
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?
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?
8. HOW DO YOU DOCUMENT THIS INFORMATION?
9. 9 README EVERY REPO SHOULD HAVE A README • What is this? • Where to start?
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.
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.
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.
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.
14. DIAGRAMS
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)
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)
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)
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)
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)
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)
21. HOW MUCH TIME DO YOU HAVE?
23. IF NOTHING ELSE
24. 2 4 IF NO ONE KNOWS WHAT IT’S FOR, IT MIGHT AS WELL NOT EXIST
25. 2 5 ALWAYS MAKE A (NON-EMPTY) README
26. Audrey Troutt @auditty audreytroutt
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