JazzCon Notes: Going Beyond "Good Enough" Documentation, Hannah Joy Lehman

Goal:

3 things:
1. enable to be more effective w/ docs
2. enable you to hate writing documentation LESS (not fall in love with it necessarily)
3. use docs in a way that allows you to focus more on your code

Who?
Why?
What?
How?

Who? —
Hannah Lehman
Software Engineer at Dude Solutions, Raleigh NC
Also a Meetup organizer
Tons of code bootcamps coming out
Noticed a strong need for community among people changing careers, especially for adults leaving a different career behind.

Being a career changer — why I care about documentation
Started in Architecture (physical)
Housing crash, layoffs, student loan debt, etc.
What am I going to do?
Switched to technology
Also a strong background in a variety of writing projects for family, edited a book, published poetry, blogged for 2+ years, articles in Medium, etc.

Today’s talk expectations: Developers writing documentation for other developers (not for users, customers, etc)

Why? —

Why do I care about this topic?
Entered a new career, first job as a developer, new tools and languages, hadn’t used them before.
“I”m smart, what can I do? I can write documentation!”
Immediately added value to teams as a new developer.
Made on-boarding easier
Able to join teams and think “I don’t care what docs are there initially, because writing the docs helps me understand the code”
A chance to combine writing with getting into the codebase
Documentation isn’t going anywhere — printed books are still preferred overall more than audio books, kindle, etc.  As long as humans are writing and using code, we’re going to need documentation.

Why should YOU care?
Last year 25000 new code bootcamp grads in the US.
50000 CompSci graduates last year
60% of technical positions are not filled
REALLY good chance you’ll be on a team with a junior dev (if you aren’t already)
Want to make their lives easier to make your own live easier

Think of docs as the “gateway drug to your code”

Look for an npm package, find 1 with a cool name, lots of commits, pull requests, etc, go to look at the docs and can’t tell what it does so you move on?

You’re developers — you want to spend more time writing code. The better your documentation IS, the less you have to focus on it, the more time you have for writing code.

Why do we as developers hate it so much? —
We reuse code because the thrill is gone one the problem is solved, so we can move on to the next thing.
Documentation is seen as the thing we “have” to do.
Developers are people too.
We’re human, we just want to write code, that’s how we want to spend our time.
Writing docs doens’t give us immediate return value — no “error fixed” or “all tests passed” rush.
We’re not the best at describing our own code.
Hard to write 2-sentence bio about ourselves for conferences, etc.

Also something you have to maintain — boo
Someone submits a pull request, now the arguments for your function are different, have to update the docs, etc.

Why do we hate writing docs? —
We’re not very good at describing things, naming variables, etc.
Going to docs as the new team member, docs are out of date, everyone else expects you (the new person) to update it. Boo.

“Why don’t you just fix the docs?”

If we don’t write the docs at the moment we wrote the code, it just goes into the backlog as technical debt and never gets done.
More than 1 way to write docs.
“All you have to do is go to Jira and search for JUST the right keyword” — giant pain to find what you need.

Assumptions we can/can’t make when writing docs —
Assume people are coming to your code to use it for a specific purpose
Very rarely do people puruse GitHub just to kill time, almost always because they have a problem to solve
“This library does XYZ”

Assume people know how to use the terminal

Don’t assume -
prior use of your code
just because 30 people have starred it, don’t assume everyone knows how to use it
write docs for the person coming to your repo for the first time

don’t assume everyone has all the dependencies are there
list out what’s needed before your library will work

don’t assume documentation is just a formality
“readme”
docs are only helpful if they’re helpful

What constitutes “good enough” documentation? —
Bare minimum in your docs:

1. Basic Description
Don’t start w/ ‘npm my package’
start with what does your project DO?

2. installation
do i need to clone your repo?
do i need to run some magic command line options to get it started?

3. Give an example or 2 of how to use your code
don’t need to list every single feature, just a few good common examples is fine

Noderize - Node app project
Docs are clear on what it does, how to install and use it
Bare minimum plus a bit more useful info in the docs.

We think of keeping our code simple, documentation should be the same.
Don’t use 18 different fonts and styles.
Everything doesn’t need to be H1 and H3 and H7, etc
When in doubt, use less styling.

Beyond “good enough” docs —
DO

List of prerequisits
Angular CLI
Firebase
Node

Also, linking to those other docs. Subliminally saying “it’s not my job to teach you these things, open a new browser tab and read those docs then come back here”

Don’t waste your time teaching people how to use the terminal.
Going to hate writing docs more if you go out of your way to write about things people don’t even need.

Troubleshooting tips
“In case this doesn’t happen, navigate to…”
Author knows their own code, gives me confidence to use it.
they’ve done the work to debug when things go weird
“If you don’t do these things first, it will take us a lot longer to try and help you fix problems.”
Gently nudges the reader to do some work.

Features are listed.
For larger apps, maybe a table of contents.
Or “3 specific features for this repo” get highlighted, etc.
Clear that if I don’t want those things to happen, this is not a repo I want to use. User won’t waste time.

Sense of humour in the docs - gives me a better feeling when trying to use the code.
If you don’t have a sense of humour in your writing, just try to be yourself.
(Unless it’s for a day job and lots of people need it written in a very professional capacity.)

How NOT to write documentation —

Don’t bury important things in large paragraphs.

Examples should be simple, not verbose.

“For this tool, all you do is [cmd name]” rather than 15 different examples.

Keep it simple, just like you do your code. Docs should be no different.  We tend to think of docs as “verbose” but less is more when it comes to docs.

In code, we do DRY. But in docs, we get very repetitive.
If you write docs once, you can just say “check out the README”.
Why repeat yourself verbally in docs when you don’t do that in your code?

Don’t be a jerk.
“I’m a senior developer, I don’t need to be write documentation.”
It’s 2018 - get over it.
You can often translate the idioms you use for writing code and comments, and apply them to writing documentation.

How many times have you drawn SQL diagrams on a dry-erase board in a meeting? Take a picture, that can inform your documentation.

Ask for help.
Form a relationship with someone at work — write docs for their code, they write it for yours.
When you have to have code reviews anyway, having someone document it, gives you a chance to do both, kills 2 birds w/ 1 stone.

Document as you go
Any time we put something off until then end, it’s much more annoying.
Harder at first when an architecture isn’t fully defined.
Use your comments in your code.
Do a global search in your code for comments — there is some boiler plate for your docs.
If you don’t like to write, do video documentation — some people just want to talk thru their code. That’s a tool available to us.

You can find Hannah on Twitter.