In the world of software engineering, crafting a well-designed system requires careful planning and documentation.
While waterfall delivery may be a thing of the past, two key design techniques continue to shape today's software delivery: high-level designs (HLD) and low-level designs (LLD). These design practices play a pivotal role in guiding the creation of robust and scalable software systems.
Before continuing, I should state that I'm not referring to those horrendous red-tape style Word docs we all hate. The design content should be delivered incrementally — as required — via modern collaboration tools.
What is an HLD?
A high-level design (HLD) document serves as a blueprint — outlining the overall structure, components, and relationships of a system, platform or project. Its purpose is to provide a clear and concise overview of the system's architecture, key functionality, interfaces, and major design decisions.
What is an LLD?
A low-level design document/s provides detailed specifications for the implementation of a system, platform or project. It covers technical details such as physical data models, integration/data flows, algorithms and platform configurations.
There are often multiple LLD documents and artefacts that describe the implementation of a system.
Documentation strategies for agile projects
While the majority of rational technical minds acknowledge the value of design docs, the agile zealots often regard it as an unwelcome rash.
Here are some strategies to help get them onboard:
Iterative Approach: Instead of creating extensive upfront design documents, adopt an iterative approach. Start with a high-level design that outlines the overall architecture and major components. As the development progresses, iteratively refine and update the design documents based on evolving requirements and feedback. Visual Modelling: Utilise visual modelling techniques to communicate design concepts effectively. Use diagrams, flowcharts, flow diagrams, or data models to represent the system architecture, relationships between components, data flows, and interactions. These visual representations can be more concise and understandable than walls of text.
Collaborative Workshops: Conduct collaborative workshops or design sessions involving key stakeholders, engineers, and designers to collectively brainstorm and define the design. Encourage open discussions, knowledge sharing, and collaboration to capture diverse perspectives and ideas. These sessions can help in rapidly evolving the design and identifying potential issues or trade-offs. Just-In-Time Documentation: Agile projects prioritise working software over comprehensive documentation. Instead of creating detailed HLD/LLD documents upfront, focus on just-in-time design. Capture the design decisions and rationale as they occur during development or during design discussions. Keep the documentation lightweight, concise, and relevant to the current sprint or iteration.
Check out my article below on using architecture decision records in an agile environment.
Design Patterns and Guidelines: Establish a set of design patterns, guidelines, or coding standards specific to your project. These guidelines provide a common understanding of the preferred design principles, coding practices, and architectural patterns to be followed. Document and share these guidelines with the development team, ensuring consistency and maintainability of the codebase.
Version Control: Treat design documents as living artefacts that evolve over time. Leverage a docs-as-code approach to track changes and maintain a historical record of design iterations. This helps in reviewing and reverting changes, as well as collaborating with other team members.
Check out my article below on using docs-as-code for controlled documentation.
Final Thoughts
Design documentation provides a clear vision, guiding development teams towards a common goal while aligning stakeholders' expectations.
It also serves as a valuable reference, supporting future modifications, mitigation of risks and facilitating collaboration among teams.
Remember: the key is to strike a balance between providing enough design documentation to guide the development process and avoiding excessive documentation that becomes a hindrance to agility and flexibility.
Defy the agile purists, and use common sense — document the system.
I hope you found this interesting. The Yam Yam Architect.
If you enjoy reading stories like these and want to support me as a writer, consider signing up to become a Medium member. It's $5 a month, giving you unlimited access to stories on Medium. If you sign up using my link, I'll earn a small commission.