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.
HELPING FUTURE YOU:
WHY DOCUMENT CODE?
IF NO ONE
IT MIGHT AS
WELL NOT EXIST
WHO IS THIS
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
If enough time passes this is
the same as making
documentation for other devs.
Future you has forgotten
THIS IS FOR PEOPLE WHO
AREN’T DEVS OR WHO WILL
CONSUME BUT NOT UPDATE
They need to understand what
this is, how it works, and how
to use it.
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
• Can you assume they are familiar with the product or app as a
• Can you assume that you or someone familiar with the code will
be around to help them?
•How the code works?
•How to build, test, update, release it?
•How to use the code?
WHAT DOES YOUR READER NEED TO KNOW?
HOW DO YOU DOCUMENT
EVERY REPO SHOULD HAVE A README
• What is this?
• Where to start?
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.
USING MARKDOWN YOU CAN TAKE A
MORE FORMAL APPROACH TO CODE
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.
documentation/ for great reference on
Swift markdown documentation and
WIKIS AND DEVELOPER
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
You may need a search tool, navigable
outline, and many explanations, code
samples, images, diagrams, and links.
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
SHOWS THE OVERALL STRUCTURE OF A
SYSTEM AND HOW THINGS ARE
Architecture diagrams take many
different forms and can cover whole
systems or generic subsets of the app
architecture, like this MVVM diagram
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
Example usage: explain how customer
profile information is consumed,
processed, used for segmentation,
aggegated, and stored
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)
SHOWS THE PROCESS
Processes include multiple steps with
transformations or logical transitions in
UML (unified modelling language) gives
standard meaning for each of the
Usage example: explain a process for
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
SHOWS STATES OF A SYSTEM AND
WHAT TRANSITIONS EXIST BETWEEN
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.
HOW MUCH TIME DO YOU
IF NOTHING ELSE
IF NO ONE
IT MIGHT AS
WELL NOT EXIST
ALWAYS MAKE A
• Icons from Material design https://material.io/
• Key Photo by Michael Dziedzic on Unsplash
• Screenshot of
• Code comment screenshot from Fastlane
• Jazzy/Alamofire doc sample from
• RxSwift Example example from
• Wiki screenshot from Fastlane
• MVVM diagram from
• Other diagrams created in Lucidchart from default
• Welcome door photo by Taylor
Simpson on Unsplash