Don't treat technical design document as a dilemma!

Source: by Matt Hudson on Unsplash

Creating and maintaining is part of the nature of software development. After receiving the problem statement or the idea from our insight or product team, development will start, go, and finish. Time goes and after some months you want to back to the project for further changes, onboarding a new teammate, or present the problem scope and the solution to the board or stakeholders. While you have no way instead of reading all you did before, permanently ask yourself "Is this my work?", "Why did I do that in this way?", "This part is sucks!", and so on. You might ask your teammates what they remember, and most of the time this won't work as expected!

You spend so much time figuring it out and finally get it, but is the time worth it?! Could this process boosted by having some documents? But wait! Most developers don't like documenting while asking for it :). When I talk with others, they say that the code should be self-explanatory, that good code doesn't need a document as you can easily understand it, and they will be there for any changes and more. Although these statements sound good, they are not for any situation.

Keeping the code self-explanatory is a tempting approach, but like others has advantages and disadvantages. Self-explanatory code can reduce the need for extensive inline comments or external documentation, making it easier to maintain and update the codebase over time. It also enhances readability, as team members can easily collaborate on the project and understand each other contribution. On the other hand, when the project's complexity grows, keeping the style will become hard, and a lack of business logic knowledge will increase its ambiguity, collaborating on the project becomes hard and more time is needed to understand and develop to catch the goal.

Everyone agrees that clean code decreases future problems and can mitigate some, but we have to take care of the documentation, too. Documenting a technical design begins with the crucial step of preparing for the documentation process, which involves considering edge cases and breaking down the project into manageable components for organized implementation. This initial phase not only ensures that potential challenges are anticipated and addressed proactively but also sets the stage for a structured and well-thought-out documentation process.

Moving into the heart of the documentation process, it is essential to detail solutions for potential future problems, gather feedback from team members, and organize their suggestions effectively. This phase serves not only as a repository of information for current and future reference but also as a platform for collaboration and iterative improvement based on valuable input from stakeholders. By documenting feedback and suggestions cohesively, the document becomes a living entity that evolves with the project.

As the technical design document takes shape, it plays a pivotal role in facilitating communication, enhancing team understanding of project intricacies, and potentially laying the groundwork for future project iterations. By aiding in task prioritization, managing project complexity, and efficiently resolving issues while preempting potential blockers, this documentation process becomes a cornerstone of project success. Its ability to streamline communication, promote clarity, and drive effective problem-solving underscores its significance as a fundamental tool in the project's lifecycle.

However, writing the technical design document is not always beneficial. In certain scenarios, the formal creation of a Technical Design Document (TDD) may not be necessary. Firstly, for small and straightforward projects like utility scripts or basic web pages with limited functionalities, the effort invested in crafting an elaborate TDD could exceed the benefits gained, as the design might be easily grasped through informal communication. Similarly, during prototyping or exploratory phases, where ideas or technologies are being tested swiftly, a formal TDD might lag behind the rapid evolution of the design, emphasizing the need for agile experimentation and frequent iterations.

Moreover, when projects adhere to well-defined standards or established patterns within frameworks like Spring Boot or Django, where architectural decisions are implicit and documented by the framework itself, the creation of a TDD might be considered redundant. In agile development environments utilizing methodologies such as Scrum or Kanban, where adaptability and iterative progress are paramount, a detailed TDD might impose unnecessary rigidity, potentially hindering the team's flexibility in responding to evolving requirements.

Additionally, when time constraints loom large over a project, prioritizing the delivery of a functional solution within a tight timeframe might render the exhaustive creation of a TDD impractical. Instead of a formal TDD, alternative documentation methods such as informal wikis, diagrams, or well-commented code can serve as effective substitutes for capturing essential design decisions. Emphasizing clean and well-documented code as a form of documentation itself can also aid in conveying the design effectively.

Furthermore, conducting regular design reviews with stakeholders can ensure that architectural choices are refined and aligned with project goals. However, in the case of complex systems with numerous components and dependencies, critical systems necessitating heightened reliability and security, or projects involving multiple teams or developers, the structured approach offered by a TDD can prove invaluable in ensuring clarity, consistency, and effective team collaboration.

Ultimately, the decision on whether to undertake a formal TDD should be context-specific, taking into account factors such as project complexity, time constraints, and team dynamics. It is essential not to feel compelled to create a TDD if it does not significantly enhance the project's value or align with its unique requirements, acknowledging that flexibility and adaptability are key in determining the most suitable documentation approach for each project scenario.