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
64
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
67
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
技術を改善し続ける
gumioji
0
120
CloudNativePGを布教したい
nnaka2992
0
110
Rails 1.0 のコードで学ぶ find_by* と method_missing の仕組み / Learn how find_by_* and method_missing work in Rails 1.0 code
maimux2x
1
230
プログラミング言語学習のススメ / why-do-i-learn-programming-language
yashi8484
0
160
dbt Pythonモデルで実現するSnowflake活用術
trsnium
0
260
楽しく向き合う例外対応
okutsu
0
670
XStateを用いた堅牢なReact Components設計~複雑なClient Stateをシンプルに~ @React Tokyo ミートアップ #2
kfurusho
1
990
Ça bouge du côté des animations CSS !
goetter
2
150
責務と認知負荷を整える! 抽象レベルを意識した関心の分離
yahiru
8
1.3k
ML.NETで始める機械学習
ymd65536
0
230
PHPのバージョンアップ時にも役立ったAST
matsuo_atsushi
0
230
苦しいTiDBへの移行を乗り越えて快適な運用を目指す
leveragestech
0
1k
Featured
See All Featured
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
33
2.8k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
133
33k
Rails Girls Zürich Keynote
gr2m
94
13k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
7
640
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3k
Navigating Team Friction
lara
183
15k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
129
19k
A Philosophy of Restraint
colly
203
16k
Git: the NoSQL Database
bkeepers
PRO
427
65k
Designing Experiences People Love
moore
140
23k
The Power of CSS Pseudo Elements
geoffreycrofte
75
5.5k
How to Think Like a Performance Engineer
csswizardry
22
1.4k
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