“Talk to the duck.”
Of all the advice I’ve given to new programmers and writers, talking out loud to inanimate objects as an act of self-help is probably the most controversial. The thing is: it works.
The technique, which is essentially forcing yourself to articulate your problem along with everything you think might be contributing to it, is one of the most efficient early-debugging strategies. It has been called various things, but was most popularized as “Rubber Duck Debugging” by The Pragmatic Programmer.
Rubber-duck debugging isn’t just for debugging. It’s an ideal exercise for writing code documentation as well. Rubber ducks help whenever you can’t pinpoint a starting point to something that you have to accomplish. In our case, talking to the duck helps you figure out how to create documentation from scratch for a new feature, or understand which gaps need to be filled in existing code.
…
Rubber ducking documentation – where to start
Let’s get a duck and a notebook or an open text file and see how they can help create our documentation. Our goal is to talk to the duck and write an outline that will help us realize the breadth of what we need to document. This will help us break it down into manageable tasks later on. Ready?
Phase 1 – the who
No, not “The Who”, but who the audience is going to be.
Think hard about each person you know that is going to care about your code. Which developers will be using the documentation for developing additional features, or for enhancing it in the future?
Don’t forget to include your future self as a member of your audience, because you’ll certainly find that’s the case! Have you ever looked back at code you wrote a few years ago and hardly recognized the thinking that must have gone into it? All of us do. While it might be a while before anyone but you reads about your rationale for certain things, or why decisions were made as they were – your future self will need this stuff sooner than you think.
Other stakeholders might be reading the documentation as well. Does Sam in marketing sort through new features to write updates? Does Sharon in customer support have an FAQ that stays up-to-date so she can answer customer tickets? Does DevRel have all they need to make video tutorials and demo scripts to show how things work? Make sure you’re aware of this backlog.
The purpose of this stage is to yourself aware of which documentation requirements are out there.. I also really recommend spending time talking to ducks on other stakeholders desks to see what folks could really use, but might not even know to ask for.
Phase 2 – the what
This ‘what’ is the lowest-hanging fruit, but arguably the most important. It covers the code itself and APIs, and is usually based on code annotations and comments.
When you’re looking right at the code, what to write tends to flow pretty easily. Adding narratives above that is less concrete.
While doc-comment formats vary quite a bit from language to language; what you’re doing as the writer is going piece by piece and making sure that you resolve any ambiguities within your immediate view.
Phase 3 – programming endeavor: the other what
How will people be using your code? If you don’t give them any use case examples in the documentation, then the answer might very well surprise you. In some cases, the answer might even frighten you. In other words, explain what can be done, don’t wait for developers to assume.
To get yourself thinking about this in a breadth-first way, take a look at libcurl. Libcurl is the magic behind the “curl” command line utility (and so much more than that), and it can do amazing things; we know this because it’s one of the most mature and thoroughly documented libraries around.
Most programmers that encounter libcurl really just want a brief tutorial on how to send some headers and fields to a web server and then do something with the results. Documentation should support getting these folks up to speed with what they need right now, with plenty of other documentation there for them if they need to know more.
Pro tip: If you don’t have anything written down for troubleshooting and debugging, you might have overlooked the most occurring use case of them all.
And, now the duck is sort of just staring at us in a stoic, but sort of loving way. We can almost hear it say .. now you know who is going to need docs and an idea of what they’ll need.
Phase 4 – finish the outline: the where
You’ve probably got something that resembles an outline by now, or at least a short list of lists. The last step is to figure out where you’re going to host this stuff and how it’s going to be kept up to date. I’m obviously biased here – I use Swimm not just for work, but also my personal projects, and I wouldn’t be very successful if I didn’t have it automated. Try to get this nailed down soon, and keep consistent with it so it can become a part of other people’s workflow. If you need some inspiration, here’s a great tutorial on keeping Swimm docs exported and up-to-date in Docusaurus. Additionally, you can use Swimm at the pre-commit stage to enforce continuous documentation.
Conclusion
All of this sounds very simple when you write it down, and some of you might think I’m being a little silly by talking to a duck). We poke a little fun at ourselves, but we’re talking about this because despite seeming simple, documentation all too often goes unaccomplished.
We need documentation for others, including our future selves. So we need to challenge ourselves to find ways to explain what’s amazing about the stuff that we work on, so others that depend on our code to get their jobs done (be they engineers, marketers, customer success specialists or anyone else) are empowered to appreciate and convey the enthusiasm and care that went into it. Or just so they can also get their work done properly.
And, well, ducks staring back at us approvingly in their special stoic way is pretty awesome, too.
