Let Me Write That Down For You

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://ﬂic.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 ﬁxes?

@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 ﬁxes are as
rare as hen’s teeth.

@GanbaroDigital “ Source code today is effectively undocumented.

@GanbaroDigital https://ﬂic.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 sufﬁciently 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://ﬂic.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://ﬂic.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://ﬂic.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://ﬂic.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://ﬂic.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://ﬂic.kr/p/dBNNu9 Temporary Thing

@GanbaroDigital “ Don’t document disposable code. Do make sure ﬁrst
that it’s disposable!

@GanbaroDigital https://ﬂic.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://ﬂic.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://ﬂic.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://ﬂic.kr/p/7G6Jkf Document For New Users

@GanbaroDigital Learning Materials • Getting Started • Tutorials • Best
Practices

@GanbaroDigital https://ﬂic.kr/p/AzGRVv Document For Reference

@GanbaroDigital Reference Docs • classes and their public methods •
API endpoints

@GanbaroDigital https://ﬂic.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

@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 ﬂow

@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 workﬂow.

@GanbaroDigital Make writing documentation as normal writing automated tests.

Thank You Any Questions? A presentation by @stuherbert  for @GanbaroDigital

Let Me Write That Down For You

Let Me Write That Down For You

More Decks by Stuart Herbert

Other Decks in Programming

Featured

Transcript