Write Kindly for Future You
Documentation challenges us to think about tomorrow's problems today
One of my favorite things to do as a coach is to look at tasks that are unavoidable but not always enjoyable and find a way to either automate them or shift my perspective on the task so that I go from dreading it to leveraging it to grow and thrive.
Documentation can be one of those tasks.
No one would argue that documentation is valuable. We’ve all been in the situation where a bit of explanation in the documentation would have saved a lot of time and effort. But this is where teams, projects, code and communities rise or fall - on the ability of those doing the work NOW to think ahead and provide answers for questions that have yet to be asked. To look beyond what matters today and think about what might matter tomorrow will set you apart if you are serious about building trust and a thriving career.
This mindset will not only be helpful to others, but it’s also a self-serving endeavor.
It’s happened many times, a CTO and a dev looking at legacy code, frustrated and endlessly tormented. The CTO is fuming at the idiot who wrote this shit - and it turns out the answer was he did. We always think we will remember and don’t need to document, but if we don’t leave a trail of breadcrumbs for ourselves, we will forget.
Fully remote environment + High standards
Two things we believe go hand in hand.
If you do too, check out some of our current job offerings.
When we take the time to write clear and concise documentation it’s a gift to our future self. It allows us to quickly and easily make changes, improve and evolve the project. Keeping us from wasting time and effort on details that would be easily navigated with some simple documentation.
If you are interested in putting a little effort into improving you documentation efforts (and showing kindness to yourself) here are some simple hacks that make a significant difference:
Using clear language : I’m a words girl, I love using language and having a robust vocabulary is something I am always working on - however, when it comes to conveying information in the most effective way, saying things PLAINLY is going to be best. Try writing at a level that even a child could understand so that we remove unnecessary barriers.
Know your audience : A few simple questions can go a long way: Who am I writing this for? What problem am I trying to help them avoid? What will they need to do with this code in the future? How can I answer questions they will have some day?
Format for easy viewing : A giant block of text makes my eyes go blurry. It’s hard to scan quickly and find the useful information. Again, simply asking the question: Who is going to read this and for what purpose? can help as you group information, add bullet points, leave space and use short sentences.
Use AI tools: AI can analyze your code, interfaces, and systems to automatically generate initial drafts of documentation. Tools like Doxygen, ReadMe Generator, and GitBook can scan your code and instantly create outlines, overviews, and starter content for your docs. This saves you time and ensures key information is captured. You then review, edit, and build upon the draft. We also love to resource MarkDoc.
Reward yourself for a job well done: At the end of each week, check in with your code. How much documentation did you write? See if you can hit a certain amount and reward yourself when you do. Make it a challenge that feels rewarding and it will become a habit in no time.
When quality documentation is built into the culture of how you work, you create an environment where knowledge and best practices are shared, not siloed. We see ourselves as interdependent contributors rather than independent coders. We are not interested in simply creating a quick fix that gets the job done, but building an environment that can grow and evolve easily because we know that nothing happens in a bubble and growth emerges effortlessly when we build it into our processes.
What did we miss? Any documentation tips and best practices that help in your process? We’d love for you to share them with us.
Write Kindly for Future You
Documentation challenges us to think about tomorrow's problems today. (A Re-write)
One of the aspects I enjoy most as a coach is finding ways to transform unavoidable yet unenjoyable tasks. My goal is to automate or change my perspective on these tasks, turning them from something I dread into opportunities for growth and success.
Documentation is one such task that falls into this category. We all recognize the value of documentation. We've all experienced situations where a little explanation in the documentation would have saved us significant time and effort. The success or failure of teams, projects, code, and communities often depends on the ability of those doing the work today to anticipate and provide answers to questions that may arise in the future. By looking beyond the immediate needs and considering what might matter tomorrow, you can set yourself apart and build trust, paving the way for a thriving career.
Adopting this mindset not only benefits others but also serves your own interests. It has happened countless times: a CTO and a developer grappling with legacy code, frustrated and tormented. The CTO vents frustration at the supposed incompetence of the person who wrote the code, only to realize that they are the culprit. We often think we will remember everything and don't need to document, but without leaving a trail of breadcrumbs for ourselves, we are bound to forget. Taking the time to write clear and concise documentation is a gift to our future selves. It enables us to make changes, improvements, and project evolution quickly and effortlessly. Clear documentation prevents us from wasting time and effort on details that could easily be navigated with a simple reference.
If you're interested in improving your documentation efforts and showing kindness to yourself, here are some simple hacks that can make a significant difference:
Use clear language: While having a robust vocabulary is valuable, when it comes to conveying information effectively, simplicity is key. Strive to write at a level that even a child could understand, removing unnecessary barriers.
Know your audience: Asking yourself a few simple questions can go a long way. Who is the intended audience for this documentation? What problems can it help them avoid? What will they need to do with this code in the future? How can you address their potential questions?
Format for easy viewing: Large blocks of text can strain the eyes and make it difficult to quickly scan and find useful information. Consider the purpose and audience of your documentation and structure it accordingly. Use bullet points, clear headings, ample white space, and concise sentences.
Utilize AI tools: AI-powered tools can analyze your code, interfaces, and systems to automatically generate initial drafts of documentation. Tools like Doxygen, ReadMe Generator, and GitBook can scan your code and provide outlines, overviews, and starter content for your documentation. This saves time and ensures that crucial information is captured. You can then review, edit, and expand upon the initial draft. Another valuable resource is MarkDoc.
Reward yourself for a job well done: At the end of each week, take a moment to evaluate the amount of documentation you've produced. Set a target for yourself and reward yourself when you achieve it. Transform it into a satisfying challenge that motivates you, and soon it will become a habit.
When high-quality documentation becomes ingrained in your work culture, you create an environment where knowledge and best practices are shared, rather than isolated. Embrace the mindset of being an interdependent contributor rather than an independent coder. Avoid aiming for quick fixes and instead strive to build an environment that can grow and evolve effortlessly. Remember, nothing happens in a vacuum, and incorporating growth into your processes yields remarkable results.