Conquer Your Fear of Documenting in 9 Simple Steps

A team without strong communication skills is like a car without wheels. You won't get far, if at all, anywhere. You can walk, sure, but needless to say that it will take you longer to get to your destination.

Accordingly, it is crucial for any organization to make sure that there are set and clear communication guidelines, platforms, and mediums to help teams achieve their goals faster and more efficiently. Even more so now that the sanitary crisis has completely changed the way we communicate by forcing countless organizations across the globe to work remotely.

While many platforms like Zoom, Teams, and Slack ensure great verbal communication, it is important to not underestimate the power of written communication within your organization. Sure, this can be ensured with instant messages and e-mails, but there is an underestimated superpower that many teams overlook and that is documenting your work.

Documenting your work does much more than just helping your team getting $#!t done, and that's what we'll explore in this post.

Why Should You Even Care?

It is no secret that one of the most important and efficient strategy for getting through a technical interview is to THINK OUT LOUD.

You need to share your thought process out loud with your interviewer/recruiter when trying to solve a given problem. Doing so, more often than not, is more significant than solving the actual problem, as it lets your recruiter evaluate your communication skills and your abilities to collaborate.

Unfortunately, this is not your average college exam where you toss in the trash all your efforts after you hand in your paper to the teacher, and leave the classroom to go meet your buddies for a night out. If you passed the interview, that's great. Now, it's time to keep that job. Therefore, thinking out loud shouldn't be something that you leave behind after the interview. You should, unquestionably, continue to leverage and perfect that skill throughout your entire career. This is the skill that got you the job, after all.

Does That Mean More Meetings?!

Hell, no.

But it does mean more writing. Ugh, I know, yet another thing to add to your team's to-do list. However, it offers loads of advantages that make it well worth the time and effort, trust me.

As you might have realized already, developing a whole service, a component or just a simple feature are all results of team members working together. In fact, one of the main purposes for PR's (Pull Requests) is to set the stage for open communication within a team. PRs not only prevent broken or bad code from getting into production environments, but they also help us improve our design and problem-solving skills, expose us to different point of views, and can even generate new ideas.

Just like PR's, documenting your work encourages open communication between team members; it is the continuity of thinking out loud. That's why documenting your work goes way beyond just a simple formality. I like to think of this process as the extension of a PR.

Communication and collaboration should be at the core of your team's values and so, by documenting your work, you are contributing to maintaining a strong and healthy team structure. This process also prevents your team to enter what I like to call the unintentional information hoarding hell, scary I know.

As the author of the Documentation Best Practices article best put it: "Your mission as a Code Health-conscious engineer is to write for humans first, computers second. Documentation is an important part of this skill". Your documentation is the story of your code. It's an open book for your thought process, where your team members and yourself can find helpful resources related to your project and what you are currently working on.

What Are the Benefits?

Documenting your work has two categories of benefits. Those two categories are the immediate benefits and the long-term benefits.

Immediate benefits:

Immediate benefits are benefits that you and your team immediately benefit from when documenting your work, duh. Here are a few examples:

• It sets the stage for open communication on every aspect of the building process, as you're letting everyone in on the ideas that lead to architectural and design decisions.
• It helps you and your teammates understand the scope of your project better as you get a more visual and concrete representation of your thought process.
• It helps your team members rapidly understand what you're working on; therefore better contribute to the PR reviews.
• Furthermore, it helps prevent future bugs down the road as writing down your ideas is helpful for spotting bottlenecks, weak architectural design, overkills, and bloated workflows in the early stages of the development process.

Long-Term benefits:

Long-term benefits are benefits that you, your team and other colleagues will continue to benefit from, even long after a project is finished. Here are a few examples:

• If other team members need to step in on something, they are able to contribute to the project sooner and more easily, as they won't have to spend hours tracking down details and directions to start coding.
• The latter applies to yourself as well. If you go back to an old project of yours, you'll be able to pick up where you left from sooner and more confidently.
• It adds value and quality to your work by mirroring all the engagement behind every aspect of the building process and by educating the readers.
• As team members come and go, it's crucial that knowledge is not kept to one employee only, but rather shared within the team. It facilitates change inside the company, makes hiring and onboarding much easier, and prevents information hoarding.
• It creates consistency by ensuring that the same information, processes, and plans are being consumed by everyone in the team.
• Good documentation not only mirrors your thought process, but also collects all the necessary information about a task and/or a project in a centralized and organized place. This ensures that your teammates don't go down a rabbit hole trying to understand what you are doing, therefore cuts down on duplicative work. You already did the hard work, save them the googling.

💡 Did you know that the average worker spends about two and a half hours per day searching for the information they need?

Tips & Tricks

Hopefully, by now, I've convinced you that documenting your work should be an integral part of your daily workflow. In this section, I'll discuss some tips & tricks on how to get started. If documenting your work is already something you're familiar with, perhaps you'll still pickup something helpful. Keep reading!

Just like creating a mockup and a wireframe when you're designing a website, you should start documenting your work at the very beginning of your project. You can even document the thought process that led to the project idea in the first place! There are many ways to go about this and, as you get used to documenting your work regularly, you'll develop your own strategies. However, to make the most of your documentation efforts, there are (you guessed it), a few common guidelines that you can follow to structure your documentation.

• Follow this structure: Intro (Opening Remarks, Build-Up) → Conclusion (Design architecture and decisions) → Thought Process (Explanation, Research) → Extra (User Cases, Resources)
• If the documentation is long, add a table of content at the beginning of your documentation
• Say what you mean simply and directly.
• Keep it short and useful. As written by the author of the Documentation Best Practices article: "Docs work best when they are alive but frequently trimmed, like a bonsai tree".
• Get into the habit of updating your documentation frequently
• To avoid scope creep, try to keep your documentation linked to a single User Story
• Leverage the tools provided by your organization's writing platform to add visual resources, links, etc.
• Get into the habit of reviewing other documentation and contributing to them as well; this will help you get better at writing!
• Set an environment in your team's wiki platform for each project, and keep every doc under one main project directory. Break down that structure as necessary.

Don't worry about your documentation being perfect. News flash: docs are never perfect - they are messy and should be. The purpose of keeping a project wiki is to jot down your thought process, set the stage for open communication within your team, and encourage the process of building in public.
Focus on keeping it clean and practical. You'll get better with time.

During my internship, I had the chance to collaborate with the former system architect of my team, who generously and gladly shared with me all those tips & tricks to build strong and useful project documentations. These simple guidelines really helped me grow as a developer, and I hope that you can now benefit from them as well.

What Next?

As projects grow, wikis grow. Sometimes, it's good to revisit old documentation and clean up a little. This habit ensures a good and healthy wiki environment for everyone in the team. A good way to go about this is to start by deleting what you are certain is wrong and, then, including your team members in the process.

Conclusion

As stated in the beginning of this article, documenting your work goes way beyond just a simple formality. Prioritizing documentation within your organization means you and your team will build strong resources that you'll be able to rely on.

From covering the unexpected absence of a team member to tackling an unfamiliar project, you and your team will be able to overcome these challenges more easily and confidently. The process of documenting your work will increase transparency within your team and encourage a more collaborative and strategic culture. You'll all be able to make smarter decisions as information won't be locked away in one person's head only, therefore avoiding the unintentional information hoarding hell.

I really hope this post was useful for you and that you learned something. I encourage you to share the above advantages to your team members and find ways to incorporate this process in your day-to-day tasks.

Thank you for reading!

P.S.: To thank you for reading this far, I've provided you with a free template to get your feet wet with documenting your work. Head over to the page below 👇🏻
Project Wiki Template
💡 Follow me on Medium, Twitter, and LinkedIn!