You already know that documentation is important, but it can be hard to consistently create documentation over the course of your team’s day-to-day. We have good news: creating a healthy documentation habit might not be as difficult as you think. Here are five tips to get started:
1. Make time to save time.
Set aside small amounts of time for daily close out/clean up. Close out/clean up is the digital equivalent of cleaning off your desk before you leave your office for the day. For developers, it means writing down a summary of the problem you are working on, your exploration progress, and an explanation of the solution. For designers, this could mean labeling your artboards or layers, removing duplicates of the same component from your Figma file, etc.
At first, it helps to make this time an actual daily calendared event for your team to make it clear that close out/clean up time is not optional. Over time, this may become enough of a habit that the time block isn’t needed.
2. Templates are your friend.
Templates make documentation simple to create, modify, and share. As a team, create templates for tickets, PR descriptions, and product requirements.
First break down your goals into 3-5 questions that you’re trying to answer, then create templated fields to document the answers to those questions. Start with only the most important things you need to know and remember that you can iterate on your templates as your team grows more comfortable with the documentation habit.
3. Teamwork makes the dream work.
Documentation doesn’t have to be a solitary act. Pair on documentation just like you would pair on a tricky ticket. Give and receive feedback on your documentation, and iterate on it as team needs change.
Brand new team members bring valuable fresh eyes to a project. When onboarding a new team member to a codebase, keep notes on all the questions they had to ask. This can help identify the holes where documentation is missing and most needed.
4. Know what not to document.
Don’t document internal code that will change; only document the boundaries and interfaces the code establishes.
And don’t be afraid to delete or update outdated, incorrect documentation. It only adds more confusion!
5. Don’t just create it — use it.
Share documentation when someone asks a question that is already documented… and keep sharing every time they ask. Try to instill a team habit of looking in the documentation first before asking questions.
Need support in evolving your team’s documentation practices? Send us a message.
