The Vital Role of Documentation

Ever been deep into a project and then taken a break, only to come back and have no clue where you left off? You're not the only one. That feeling of confusion is exactly why documentation is a game-changer. 

Within the team I'm part of, we make sure to document everything. It's just as important as the coding itself. This way, we don't have to guess how something works or have long meetings about it. Sharing technical notes within the team is incredibly valuable and impactful, opening up opportunities for troubleshooting and dialogue. Good notes save us so much time and trouble. And here's a tip: the best notes are actually for you. 

In today's remote work era, this isn't just a nice-to-have but an essential.  When everything we document can be searched and found, it doesn't just make information easy to find but levels up our whole team's skills. More knowledge at our fingertips means we can do our jobs better and faster.

However, we need to carefully think about where we put this documentation; it should be easy to find and look good. Keeping the documentation up-to-date and useful is key to making it work well. Here are some tools we use to share documentation internally:

Notion

Notion is a really versatile platform that lets us organise documents in a way that's both appealing and user-friendly for engineers. It is one of the first tools you'll have access to when joining Yellow Card to be up-to-date with onboarding, projects, internal tools and internal processes. It's easy to use and helps keep everything in one place. 

Swimm

Swimm is another tool we started using to complement Notion, especially for code-related documentation. It's easy to integrate directly with our codebase, making it simpler for engineers to create, maintain, and access documentation alongside their code. This ensures that as our projects evolve, so does our documentation.

Github

Github is yet another tool that engineers utilise, specifically through README files. These files provide information on how to get started on a project, test it, and set up the environment, among other things.

Adopting a Documentation Culture

Embracing documentation is an excellent approach to making knowledge accessible to everyone in the organisation, regardless of their role or location. This approach is especially critical in a remote environment where direct, face-to-face interactions are less frequent.  

Easily accessible documentation encourages collaboration between teams. Engineers are more likely to engage with new projects when they notice a strong emphasis on thorough documentation. To achieve a documentation culture that truly benefits the organisation, here are some actionable strategies you can consider:

• Encourage a Mindset Shift: Shift the perception of documentation from a tedious task to a valuable asset. Highlight the direct benefits to the team and organisation, such as reduced onboarding time, fewer repetitive inquiries, and a solid basis for decision-making.
• Promote Ownership and Accountability: Encourage team members to take ownership of their areas of expertise by documenting processes, decisions and learnings.
• Recognise and reward contributions to the documentation: This could be through leaderboards or simply acknowledging the efforts in team meetings.
• Iterate and Improve:  Regularly review your documentation to ensure it remains relevant, accurate and useful.

Good documentation is more than just a productivity booster; it enables scalability and fosters innovation. As we continue to evolve and grow, let's remember that the documents we create today are not just for the present team but for future generations.

Lastly, write everything down.✍️ There’s a lot always hidden beneath the surface. Next time a thought pops up like, “I’ll remember this, No need writing this,” Imagine a giant neon “Oops!” sign flashing above your head.