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
75
Coding Standards That Improve Quality
stuartherbert
0
150
ES-CQRS and GDPR: When Immutability Meets Reality
stuartherbert
1
820
The Container End-Game: An Introduction To Kubernetes And Minikube
stuartherbert
0
140
Multi-Variance: API Versioning For Software Libraries
stuartherbert
1
74
Zend Expressive - An Introduction For API Building
stuartherbert
0
640
Automate, Automate, AUTOMATE!
stuartherbert
0
150
JSON Schema For Validating API Requests
stuartherbert
1
160
Designing For Disaster - Preparing Your Code For Emergencies
stuartherbert
1
240
Other Decks in Programming
See All in Programming
関数型まつりレポート for JuliaTokai #22
antimon2
0
150
Code as Context 〜 1にコードで 2にリンタ 34がなくて 5にルール? 〜
yodakeisuke
0
100
Haskell でアルゴリズムを抽象化する / 関数型言語で競技プログラミング
naoya
17
4.9k
iOSアプリ開発で 関数型プログラミングを実現する The Composable Architectureの紹介
yimajo
2
210
Kotlin エンジニアへ送る:Swift 案件に参加させられる日に備えて~似てるけど色々違う Swift の仕様 / from Kotlin to Swift
lovee
1
250
Gleamという選択肢
comamoca
6
760
Result型で“失敗”を型にするPHPコードの書き方
kajitack
4
270
第9回 情シス転職ミートアップ 株式会社IVRy(アイブリー)の紹介
ivry_presentationmaterials
1
230
Bytecode Manipulation 으로 생산성 높이기
bigstark
2
370
git worktree × Claude Code × MCP ~生成AI時代の並列開発フロー~
hisuzuya
1
430
What Spring Developers Should Know About Jakarta EE
ivargrimstad
0
210
GraphRAGの仕組みまるわかり
tosuri13
7
480
Featured
See All Featured
Six Lessons from altMBA
skipperchong
28
3.8k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
Code Reviewing Like a Champion
maltzj
524
40k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
Stop Working from a Prison Cell
hatefulcrawdad
270
20k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
32
2.3k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
Code Review Best Practice
trishagee
68
18k
Making the Leap to Tech Lead
cromwellryan
134
9.3k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
7
700
We Have a Design System, Now What?
morganepeng
53
7.7k
Producing Creativity
orderedlist
PRO
346
40k
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