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
62
Coding Standards That Improve Quality
stuartherbert
0
140
ES-CQRS and GDPR: When Immutability Meets Reality
stuartherbert
1
760
The Container End-Game: An Introduction To Kubernetes And Minikube
stuartherbert
0
120
Multi-Variance: API Versioning For Software Libraries
stuartherbert
1
63
Zend Expressive - An Introduction For API Building
stuartherbert
0
630
Automate, Automate, AUTOMATE!
stuartherbert
0
130
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
よくできたテンプレート言語として TypeScript + JSX を利用する試み / Using TypeScript + JSX outside of Web Frontend #TSKaigiKansai
izumin5210
6
1.7k
みんなでプロポーザルを書いてみた
yuriko1211
0
260
2024/11/8 関西Kaggler会 2024 #3 / Kaggle Kernel で Gemma 2 × vLLM を動かす。
kohecchi
5
920
Webの技術スタックで マルチプラットフォームアプリ開発を可能にするElixirDesktopの紹介
thehaigo
2
1k
Jakarta EE meets AI
ivargrimstad
0
160
ローコードSaaSのUXを向上させるためのTypeScript
taro28
1
610
Creating a Free Video Ad Network on the Edge
mizoguchicoji
0
120
Macとオーディオ再生 2024/11/02
yusukeito
0
370
CSC509 Lecture 12
javiergs
PRO
0
160
初めてDefinitelyTypedにPRを出した話
syumai
0
410
Amazon Qを使ってIaCを触ろう!
maruto
0
400
聞き手から登壇者へ: RubyKaigi2024 LTでの初挑戦が 教えてくれた、可能性の星
mikik0
1
130
Featured
See All Featured
Thoughts on Productivity
jonyablonski
67
4.3k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
506
140k
Designing on Purpose - Digital PM Summit 2013
jponch
115
7k
Facilitating Awesome Meetings
lara
50
6.1k
Testing 201, or: Great Expectations
jmmastey
38
7.1k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
44
2.2k
How to Think Like a Performance Engineer
csswizardry
20
1.1k
Making the Leap to Tech Lead
cromwellryan
133
8.9k
Building Your Own Lightsaber
phodgson
103
6.1k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
126
18k
Music & Morning Musume
bryan
46
6.2k
Put a Button on it: Removing Barriers to Going Fast.
kastner
59
3.5k
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