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
58
Coding Standards That Improve Quality
stuartherbert
0
130
ES-CQRS and GDPR: When Immutability Meets Reality
stuartherbert
1
690
The Container End-Game: An Introduction To Kubernetes And Minikube
stuartherbert
0
100
Multi-Variance: API Versioning For Software Libraries
stuartherbert
1
58
Zend Expressive - An Introduction For API Building
stuartherbert
0
620
Automate, Automate, AUTOMATE!
stuartherbert
0
120
JSON Schema For Validating API Requests
stuartherbert
1
140
Designing For Disaster - Preparing Your Code For Emergencies
stuartherbert
1
210
Other Decks in Programming
See All in Programming
TCAとKMPを用いた新規動画配信アプリ 「ABEMA Live」の設計
tomu28
2
130
Milestoner
bkuhlmann
1
420
Open standards for building event-driven applications in the cloud
meteatamel
0
190
Webアプリをできるだけコードを手書きしないで作ってみる
tomokusaba
2
190
業務ツールとして使うPostman
msys75
0
120
Ruby Function Composition
bkuhlmann
1
340
Kotlin Multiplatform at Stable and Beyond (Android Makers 2024)
zsmb
0
550
Documentation for users with AsciiDoc and Antora
ahus1
0
370
Exploring the Implementation of “t.Run”, “t.Parallel”, and “t.Cleanup”
akarin
1
140
新宿ダンジョンを可視化してみた
satoshi7190
3
420
Open AI APIを使う前に知っておきたいアカウントTier の話
akki_megane
0
110
Amazon SQSコンシューマー疎結合への旅 - 出張! #DevelopersIO IT技術ブログの中の人が語る勉強会 #3
quiver
0
340
Featured
See All Featured
The Invisible Customer
myddelton
114
12k
Building Effective Engineering Teams - LeadDev
addyosmani
32
1.9k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
34
6.1k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
20
1.8k
Stop Working from a Prison Cell
hatefulcrawdad
267
19k
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
66
14k
StorybookのUI Testing Handbookを読んだ
zakiyama
13
4.6k
A Modern Web Designer's Workflow
chriscoyier
689
190k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
8
3.4k
The Mythical Team-Month
searls
217
42k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
245
20k
Into the Great Unknown - MozCon
thekraken
15
1k
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