Documentation is Essential in Software Engineering and we all need to write more of it.

Introduction

In the world of software engineering, documentation plays a vital role in ensuring the success of projects. It provides a comprehensive understanding of the software system, its components, and its functionality. While some developers might consider documentation as an unnecessary burden, it is, in fact, a critical aspect of the software development process. While many companies have well-written user guides for their users, internal documentation is just as important. My goal for this article is to inspire developers and other team members - Product Owners, Quality Assurance, Project Managers etc... to make documentation part of their BAU.

Knowledge transfer

Firstly, let's talk about the most important aspect of documenting software, and that is knowledge transfer. Knowledge transfer is essential for maintaining business continuity and ensuring that the software continues to evolve and meet the changing needs of users. Additionally, comprehensive documentation helps new team members or external contributors to quickly familiarize themselves with the software, reducing the onboarding time and facilitating a smoother transition. It will also provide domain knowledge to new devs who have not worked in that particular domain i.e.: law, finance, aviation etc...

Documentation ensures the transfer of knowledge from one generation of developers to the next. When a software project is handed over from one team to another, or from one organization to another, documentation becomes a crucial asset. It provides insights into the design choices, implementation details, and overall project context. Properly documented projects eliminate the need for reverse engineering or spending excessive time deciphering the existing codebase. In my personal experience, one of the most frustrating things I have had to deal with is taking over a poorly written piece of software that was acquired externally. This particular piece of software had many architectural design flaws. And of course, very poorly documented. It took our team a tremendous amount of time to dig through the maze-like architecture. Not only this but trying to fix bugs and adding features took substantially longer and fixes were released to production without much confidence.

Good habits take time to build

Most (if not all) of us start our careers as junior developers. Junior developers often find themselves immersed in coding tasks and eager to make their mark in the field. And the last thing any developer starting out in this field would think about is writing documentation. I, in particular, thought this is a job for senior devs. At least that was my thinking when I got my first dev job. But now looking back, I realised that was a mistake on my part and I should've developed a habit to contribute to the documentation.

When junior developers actively contribute to documentation, they gain a deep understanding of the project's architecture, requirements, and design decisions. This process allows them to comprehend the bigger picture and aids in developing a solid foundation of knowledge. By immersing themselves in the documentation, they will gain insights into best practices, coding conventions, and project standards, enhancing their ability to write clean, maintainable code.

Documentation offers an opportunity for junior developers to analyze and articulate complex problems and their solutions. By documenting their thought processes, they refine their problem-solving skills and enhance their ability to explain technical concepts effectively. Through the act of documenting, junior developers gain a deeper understanding of the challenges they face, the solutions they implement, and the reasoning behind their decisions. This skill development not only benefits the immediate project but also lays a strong foundation for their professional growth in the long run.

Documentation is everyone's responsibility - not just the developer's

Documentation facilitates collaboration among team members. In software development projects, teams often consist of multiple individuals working together to achieve a common goal. Documentation serves as a means of communication, allowing team members to share their ideas, insights, and progress with their colleagues.

I have been rambling on and on about documentation, but mostly from a developer's perspective, but the responsibility should be with everyone who works on the project. By documenting the project's business requirements, architecture, design decisions, and implementation details, team members can understand the system as a whole and work together more efficiently. It serves as a reference point that promotes shared knowledge and understanding among team members, ensuring that everyone is on the same page. Moreover, contributing to documentation ensures that knowledge is not locked inside the heads of specific individuals, preventing the risk of information loss when team members leave or move on to other projects.

To hammer on this point, everyone should contribute to documentation as knowledge is widespread among the team. As a piece of software grows in complexity, the team can easily look up relevant information in the documentation instead of doing what I would call "doing it the corporate way" of setting up a meeting, making sure the required people are available, recording the meeting etc... A more hassle-free approach is to point someone to the documentation for the knowledge.

Final thoughts

As developers, we generally think our job is to write code and debug problems. Although this is true, we also need to consider the other aspect of Software Engineering, and that is writing documentation that will be a reference point for other team members. I hope I have inspired my readers and make writing documentation a part of their BAU.