As Swimm’s main user advocate, I spend a lot of time helping folks with technical things in their documentation flow. A typical week for me involves fixing quirks in continuous integration flows, helping folks wire up their intranet portals to their Swimm documentation, and other mostly technical things. That’s what I expected I’d be doing initially when I took on the role.
But, there’s another thing that I spend a considerable amount of time doing that I really like, but didn’t anticipate: I spend a lot of time helping people get past the sometimes intimidating blank document starting screen and into a plan where documentation creation starts to snowball, much like paying down a credit card snowballs when you focus your energy correctly. Something that I’ve discovered through doing this is, knowing how to write and knowing how to start writing are really two different skills.
Curious? Let’s jump in!
1 – Pick a main thing & factor it down
To extend the credit card analogy a little, this is the process of picking the gap in your documentation that is currently costing you the most in interest. This will not necessarily always map to the part of your code that generates the most questions, or confusion; if there’s something that always takes an hour to explain but only comes up a few times a month, it probably has a higher “interest rate” than something that only takes a few minutes to explain. You will eventually get to all of it, so don’t feel like you’re ignoring parts – remember we’re just figuring out where to get started.
Got a thing in mind? Good. Now, let’s start factoring sub tasks until we can’t factor them any longer. Are you documenting authentication? Okay – that’s going to mean the security classes, the rate limiting stuff, the human detection classes and that new location doodad – you get the point. You’ve broken it down to all of the supporting roles that will have to be filled in order for the documentation to be complete.
2 – Open your calendar
That list of tasks? It should probably look a lot like things that could be sorted into 15, 30 and 60 minute buckets. You’re going to need to figure out how much time each week you are willing and able to commit to documentation. Underestimate this rather than overestimate it, as a major key to this process is building on your previous success, or what we call the snowball effect. When paying down credit card debt, we think about how much over the minimum payment we can spare in order for the interest to start costing us less immediately.
A few hours a week is a great goal. Put a 15 minute event on your calendar showing you as marked busy and call it “Write about rate limiting.” After that, maybe the day after, add an event for 45 minutes to write about something that would depend on the reader first knowing about rate limiting.
Keep going until you have all of the factored components of the bigger picture laid out. Now, look at your calendar again from the monthly view – you can now point to a day where you’ll have the highest-interest technical documentation debt paid off. Make a promise to yourself that you’ll stick to the schedule, and make sure any writing sessions get moved around as needed rather than missed.
3 – Open other people’s calendars, too
Ideally, documentation doesn’t fall on one person. Many hands make light work so if you’ve identified a high-interest part of the code and think someone else might be able to write in 15 minutes what would take you an hour, consider creating an invite for them on their calendar to do it. Explain that it’s a group effort, and the best way to break up the work so nobody gets bogged down is to distribute it in a way that’s easy to track visually with calendars.
If you’re the lone soul working to get this done yourself, we see you and we love you. Don’t get discouraged, just get it on the calendar – you will be surprised by just how much knowing the day it’s going to be done can help keep morale and momentum going.
4 – Make the benefits of good documentation contagious
The best documentation is the documentation that is (1) correct and up-to-date and (2) discoverable when someone needs to learn from it. We recommend that everyone using Swimm also make use of our IDE plugins, so that developers see the availability of documentation in the midst of the code that they want to understand, and can read it right in their editor.
If we don’t yet fully support your IDE (we’re constantly working on adding more), you can take advantage of Swimm’s Docs-As-Code design, and use format translation tools like Pandoc to publish Swimm documentation in a variety of other places.
Make sure folks on your team know that they can base documentation from a recent commit SHA. If you structure and squash your commits in a way that new features are added in cumulative order, Swimm can pull snippets from all affected files that introduces something new and set up a scaffolding of sorts where you see the code you need, and just have to write a few paragraphs to explain it.
5 – Explore maintenance strategies, and couple that code
Plan on success by looking ahead to how you’re going to treat documentation more as a maintenance process and less of a production one. The single most important thing you can do while you pay off debt is not go backwards, so make absolutely certain that you’re either running Swimm’s verification checks on your CI server, or using commit hooks if you don’t have a continuous integration server.
As far as documenting the rest of your code base, and maintaining what you’ve written, we’ve identified four main documentation strategies that stand out the most. I scratch the surface a bit in this ten minute video presentation:
There’s way more to explore than I could possibly fit in a ten minute presentation, around a half an hour of total content. If you’d be interested in me giving this presentation to your company, consider becoming one of our beta users, and reach out to me at ricardo@swimm.io!
How you write your docs is your thing. Don’t let perfect documentation become the enemy of good documentation / divide the tasks, get them on your calendar and get something saved – if you stick with it, your progress will snowball quickly.
To learn more about Swimm, sign up for a 1:1 Swimm demo.
