You know what your New Year’s Resolution shouldn’t be?
Writing better code documentation.
That’s because New Year’s resolutions tend to fizzle out by the time February comes around. And improving how your organization/company/team approaches documentation is a marathon – not a sprint.
Since documentation is a critical part of the development lifecycle, the strategy here is to build documentation habits that will actually stick with you and your team.
Breaking the “documentation avoidance” habit is a great team goal for 2023. Here are five tips for getting started.
1. One doc a day
Okay, so the first time you do something, it always takes you a bit longer, but here’s what we’re proposing: onboard to Swimm and create one doc, and then another, and then a third. See with your own eyes how long (or not long, in this case) it takes to create documentation notes for just one snippet of code; create documentation from pull requests and/or commits from part of the code you want to document.
Keep it simple – code documentation is not complicated at all. In our experience, creating your first Swimm doc demystifies however it is you imagine it to be.
2. Imagine your next hire
Imagine helping onboard the next person who is hired in your company. Think about the possibility of assisting them to access treasure troves of documentation and information with the knowledge to succeed at their fingertips. Imagine them digging right into the code without you or your colleagues sitting next to them trying to, as best as you can, remember and decide what about the code you should specifically mention.
Imagine the next developer accessing the code you and your dev team have been working on – on a silver platter with documentation and playlists.
Once you can imagine this person, you will likely begin to prioritize which parts of the code need documenting first…and you can start to run and write with that adrenaline.
3. Ride the Continuous Documentation wave
Documenting code has become a tedious task for devs today. Typically, dev teams document in sprints, and documentation that is not synced with your code gradually becomes outdated very quickly.
At Swimm, we’ve solved the documentation challenge by creating Continuous Documentation so that your code is always auto-synced and updated.
Developers report a 50% productivity boost when documentation is readily available with open source and enterprise projects. Continuous Documentation has changed the paradigm for creating and maintaining code documentation, incorporating the documentation into the standard development workflow.
4. Go back to the larger goals of documentation
If you’re working on documentation and you find yourself stuck, go back to the product’s design and plans, taking a step back in reminding yourself of the big picture.
So what does this look like? Think about what you’re doing and why. Pausing for a bit, we’ve found, reorganizes your thought processes and helps push your documentation goals forward.
5. Remember that documentation is part of your team backup
Make it a mindset. Teams come and go in companies, but the code continues to evolve.
The best way to ensure that there isn’t a single point of failure in code documentation is to set and create high documentation standards within your organization.
Think of your team as a system; you want to do your best to avoid knowledge silos. Continuous Documentation is your ticket (with no expiration date) for preventing knowledge silos in your code.
Bottom line
The new year is an excellent time to switch up how you approach your goals and consider new ways of doing things. Documentation doesn’t get the credit or attention it deserves, but we know it deserves so much more of our attention in the coming year.
Jump in with Swimm this year, and sign up for a 1:1 demo.
