When was the last time you got into a heated discussion regarding how your documentation performs at scale? Probably never. No one thinks about how documentation scales, but it’s vital. Having great documentation and READMEs will ensure that your development team can iterate quickly and easily onboard new engineers when you scale. I’ll take the next few moments to share with you four great ways you can be sure your software docs are ready when your team goes from 5 to 15 developers, and even when your team goes from 15 to 150 developers.
Pick the Right Medium
It’s important to store your documentation somewhere that’s convenient for the engineers that need to review and update it frequently. Many times this means a simple README file included in your code repository. It could also be a wiki or some sort of SaaS documentation such as readme.io. Either way, you’re going to want this in the cloud so everyone who needs it can have access to the most up to date version anytime they need. You’ll probably want your docs version controlled as well, which makes the repository README file option very appealing.
Start off Strong
Low quality, unorganized documentation is impossible to keep up to date. People often avoid updating the docs or simply slap stuff onto the end once it becomes difficult to figure out how or where they need to be updated. Make it easy on yourself by starting off strong with a well opinionated and organized README, that way when something is changed there’s a definite place to change it in the README. The last thing you want is for your documentation to turn into a massive notepad where finding anything requires digging through the results of a ctrl+find. That’s not one bit efficient.
PurpleBooth’s README-Template.md is a good starting point for a readme MVP but you’re the best person to know what should be included in your own README. Here are some things you may consider including, assuming your README is your main documentation source.
- API Routes
- Object Shapes
And as always, don’t include secrets or keys in a README.
Know When to Update Your Docs
Keeping documentation up to date is a team effort. It’s important to make sure everyone knows how the living documentation fits into the development workflow. Should developers be working stories with the docs open, following along so they know where the changes are supposed to be? Or should they simply check the docs after a story is completed to see if there’s anything that needs updating? Make sure to settle on these expectations early on, that way changes in the docs are timely, reliable, and consistent. On Yipee.io we have this as part of our Definition of Done.
Avoid Documentation Where Possible
Another way to dodge the problem of keeping docs and READMEs up to date, is to avoid them from the start. Tools like Doxx, YUIDoc, and Docco are trying to solve this problem in the code base by auto-generating documentation based on the code content. There is a bit of a learning curve to getting these tools up and running, but if they fit your needs, it could save you a ton of time in the long run.
At Yipee.io, we’re also working on making documentation obsolete, but instead with deployment organization charts. Yipee.io is a GUI builder tool for containerized microservice applications. Gone are the days where you had to boot up a specialized charting application to send colleagues your new deployment architecture chart. Simply define your infrastructure in Yipee.io and your application model will always be there and you can quickly export YAML files like Docker Compose, Kubernetes and OpenShift for orchestration. Zoom, pan, and move objects anywhere on the canvas to make your diagram more readable and never deal with out of date paper charts ever again.
Interested in learning more about Yipee.io? Sign up for free to see how Yipee.io can help your team streamline their development process.