Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Let Me Write That Down For You
Search
Stuart Herbert
January 26, 2017
Programming
0
110
Let Me Write That Down For You
The importance of documenting software.
Presentation given at PHP Warwickshire.
Stuart Herbert
January 26, 2017
Tweet
Share
More Decks by Stuart Herbert
See All by Stuart Herbert
Type Integrity: The Software Engineering Behind Stricter Typing
stuartherbert
0
65
Coding Standards That Improve Quality
stuartherbert
0
140
ES-CQRS and GDPR: When Immutability Meets Reality
stuartherbert
1
800
The Container End-Game: An Introduction To Kubernetes And Minikube
stuartherbert
0
120
Multi-Variance: API Versioning For Software Libraries
stuartherbert
1
68
Zend Expressive - An Introduction For API Building
stuartherbert
0
630
Automate, Automate, AUTOMATE!
stuartherbert
0
140
JSON Schema For Validating API Requests
stuartherbert
1
150
Designing For Disaster - Preparing Your Code For Emergencies
stuartherbert
1
230
Other Decks in Programming
See All in Programming
苦しいTiDBへの移行を乗り越えて快適な運用を目指す
leveragestech
0
1.2k
dbt Pythonモデルで実現するSnowflake活用術
trsnium
0
270
Boost Performance and Developer Productivity with Jakarta EE 11
ivargrimstad
0
1.1k
良いコードレビューとは
danimal141
9
6.2k
ファインディLT_ポケモン対戦の定量的分析
fufufukakaka
0
950
Learning Kotlin with detekt
inouehi
1
190
SwiftUI Viewの責務分離
elmetal
PRO
2
280
[JAWS DAYS 2025] 最近の DB の競合解決の仕組みが分かった気になってみた
maroon1st
0
160
Datadog DBMでなにができる? JDDUG Meetup#7
nealle
0
160
ソフトウェアエンジニアの成長
masuda220
PRO
12
2.2k
Honoのおもしろいミドルウェアをみてみよう
yusukebe
1
240
LINE messaging APIを使ってGoogleカレンダーと連携した予約ツールを作ってみた
takumakoike
0
130
Featured
See All Featured
Building a Scalable Design System with Sketch
lauravandoore
461
33k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
27
1.6k
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
10
540
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
30
2.3k
Visualization
eitanlees
146
15k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
49
2.3k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
VelocityConf: Rendering Performance Case Studies
addyosmani
328
24k
4 Signs Your Business is Dying
shpigford
183
22k
[RailsConf 2023] Rails as a piece of cake
palkan
53
5.3k
Making Projects Easy
brettharned
116
6k
Transcript
A presentation by @stuherbert for @GanbaroDigital Let Me Write That
Down For You Documentation For Developers
@GanbaroDigital ?? ?? Why am I giving this talk?
@GanbaroDigital I’ve been doing this a long time.
@GanbaroDigital I’ve seen fashions come and fashions go.
@GanbaroDigital Software development principles remain the same.
@GanbaroDigital So do the needs of software developers.
@GanbaroDigital Today’s Talk 1. Why Do Docs Matter? 2. Why
Do I Doc? 3. What To Doc? 4. Tools For Docs
@GanbaroDigital Please ask questions as we go.
@GanbaroDigital Why Do Docs Matter?
@GanbaroDigital ?? ?? What documentation do you use?
@GanbaroDigital ?? ?? What do you like about those docs?
@GanbaroDigital ?? ?? Do you doc?
@GanbaroDigital ?? ?? Why not?
@GanbaroDigital Here are the reasons that I’ve heard the most
over the last 25 years.
@GanbaroDigital https://flic.kr/p/9fQMVh It’s Open Source
@GanbaroDigital “ Use the Source, Luke! - ancient Jedi proverb
@GanbaroDigital Also applies to code created and shared inside your
organisation.
@GanbaroDigital ?? ?? Straw poll: Do you comment your code?
@GanbaroDigital ?? ?? What do you write in your comments?
Docblocks? Inline comments? Explain bug fixes?
@GanbaroDigital @inheritdoc and PHP-7 strict typing are replacing docblocks
@GanbaroDigital In my experience, inline comments are rare.
@GanbaroDigital In my experience, comments explaining bug fixes are as
rare as hen’s teeth.
@GanbaroDigital “ Source code today is effectively undocumented.
@GanbaroDigital https://flic.kr/p/nD8uQL Code Is The Documentation
@GanbaroDigital “ The “Agile” way is code is the documentation
- source unknown
@GanbaroDigital Code can be readable. The Clean Code movement helps
a lot here.
@GanbaroDigital Readability standards like PSR-2 not so much.
@GanbaroDigital “ Any sufficiently advanced code is indistinguishable from magic
- with apologies to Arthur C. Clarke
@GanbaroDigital “Most developers lack the software archaeology skills required to
understand undocumented code.
@GanbaroDigital “ Code can tell you what. It cannot tell
you why.
@GanbaroDigital Code Cannot Tell You • What the requirement was
• Why the requirement is like that • Why the software was designed like that
@GanbaroDigital “ What about tutorials?
@GanbaroDigital Someone has to write this shit down somewhere. Preferably
somewhere it can be rediscovered one day.
@GanbaroDigital https://flic.kr/p/coWuU7 I’ll Be Able To Remember That
@GanbaroDigital “ Stop using it for just two months, and
see just how little you can recall.
@GanbaroDigital https://flic.kr/p/C2ofAY I’ll Always Be Here To Maintain My Code
@GanbaroDigital “ I’m the only person who works on this
code - anon
@GanbaroDigital ?? ?? Who here writes 100% of the code
in their project / app / component?
@GanbaroDigital ?? ?? What’s the half-life of your code?
@GanbaroDigital “ Most code outlives the participation of its original
author.
@GanbaroDigital ?? ?? How long have you been in your
current role?
@GanbaroDigital In our industry, permies move on to their next
employer within 4 years.
@GanbaroDigital Freelancers seldom see out the entire life of a
dev project.
@GanbaroDigital ?? ?? Who here maintains all the code that
they write?
@GanbaroDigital Larger projects and systems end up getting maintained by
someone else.
@GanbaroDigital Do You Still Agree? 1. The source is all
you need 2. Code is the documentation 3. I’ll remember everything I did and why 4. I’m the only one who will ever touch the code
@GanbaroDigital It sounds like I’m saying that everything should be
documented.
@GanbaroDigital There are good reasons to pick and choose what
to doc.
@GanbaroDigital https://flic.kr/p/62n3eY Writing Docs Takes Time
@GanbaroDigital “ Documentation can take up to 1/3 of the
time it takes to write the code.
@GanbaroDigital Budget Rules Of Thumb • If coding takes X
amount of time / effort • Testing takes up to 40% of X • Documentation takes up to 20% of X
@GanbaroDigital https://flic.kr/p/ststiY Writing Docs Is An Acquired Skill
@GanbaroDigital “ Just look at CVs and covering letters to
see how little practice developers have at writing.
@GanbaroDigital https://flic.kr/p/aHno9M Not Sure We Have The Right Solution Yet
@GanbaroDigital “ It’s easier to write long-form docs after code
has stabilised.
@GanbaroDigital https://flic.kr/p/dBNNu9 Temporary Thing
@GanbaroDigital “ Don’t document disposable code. Do make sure first
that it’s disposable!
@GanbaroDigital https://flic.kr/p/i84n6g Trivial Things
@GanbaroDigital “ Don’t document the bleeding obvious.
@GanbaroDigital “ Don’t document things no-one will ever care about.
@GanbaroDigital Why Do I Doc?
@GanbaroDigital https://flic.kr/p/agL3k8 To Truly See What I’ve Created
@GanbaroDigital “ As a developer, writing documentation is a way
of testing my work.
@GanbaroDigital To document something, you have to take a step
back.
@GanbaroDigital Documentation holds up a mirror. Take advantage of it.
@GanbaroDigital If I can’t explain it in a doc, do
I actually understand it?
@GanbaroDigital If I can’t justify it in a doc, have
I built the right thing?
@GanbaroDigital What To Doc?
@GanbaroDigital Directions For Docs 1. What needs documenting 2. Who
are you writing for
@GanbaroDigital ?? ?? What documentation do you use?
@GanbaroDigital https://flic.kr/p/8ZEoCo Document The Point Of Use
@GanbaroDigital Point Of Use • HTTP / Service APIs •
Package / Component / Library APIs • Source Code!
@GanbaroDigital ?? ?? When do you look at documentation?
@GanbaroDigital https://flic.kr/p/7G6Jkf Document For New Users
@GanbaroDigital Learning Materials • Getting Started • Tutorials • Best
Practices
@GanbaroDigital https://flic.kr/p/AzGRVv Document For Reference
@GanbaroDigital Reference Docs • classes and their public methods •
API endpoints
@GanbaroDigital https://flic.kr/p/9b24xc What About Internals?
@GanbaroDigital ?? ?? Can you safely change the internal workings
behind your API?
@GanbaroDigital “ Good interfaces hide the internal workings
@GanbaroDigital Tools For Docs
None
@GanbaroDigital Why Slate For APIs? 1. Static site - docs
can live in Git 2. Can mix tutorials and reference docs 3. Examples in multiple languages
@GanbaroDigital http://woocommerce.github.io/woocommerce-rest-api-docs/?php#rest-api-keys Slate For APIs
@GanbaroDigital https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/master/ source/includes/v3/_authentication-endpoint.md Markdown For Slate
@GanbaroDigital http://couscous.io
@GanbaroDigital Why Couscous For Libraries? 1. Static site - docs
can live with your code 2. Can mix tutorials and reference docs 3. Easy to incorporate into your CI flow
@GanbaroDigital http://ganbarodigital.github.io/php-the-missing-bits/types/GetClassTypes.class.html Couscous For Libraries
@GanbaroDigital ?? ?? What tools do you use?
@GanbaroDigital Bonus: When To Doc
@GanbaroDigital Write the docs as you write the code.
@GanbaroDigital You end up with docs and code as one
pull / merge request.
@GanbaroDigital When you tag the code, you tag the docs
too.
@GanbaroDigital Publish your docs via your CI workflow.
@GanbaroDigital Make writing documentation as normal writing automated tests.
Thank You Any Questions? A presentation by @stuherbert for @GanbaroDigital