Low Level Design Part 2: Reading and Gathering Information
Try to spend about a quarter of your design time writing experimental code and playing with code. If your LLD (low level design) is very small, write a proof of concept. If your LLD is small, medium or large, write some code to either consider an architecture for the code or to test out libraries. This will help with motivation while you are writing the doc because it feels more enjoyable to interact with a system rather than describing it. This will also reduce anxieties about unknowns and give you an opportunity to play with your design and get a feel for how well it works.
If your LLD takes more than two weeks to write, break it down into smaller documents. Large, complex LLDs can often feel overwhelming for both the author and the reader and slowly aggregate errors because they're easier to lose in the shuffle.
Review early and often. Show your LLD to one of the senior team members to gather feedback when it's still in very early stages -- they may have helpful information for potential innovations or how to avoid doing something overly complex. I often make my LLDs available as google docs as I'm writing them in case someone is interested.
The core of your document is the intro, diagrams and code snippets. Most text should be an explanation of useful details, rather than the core of the document itself. A significant portion of the people who will read your document will only have the time look at these and not the rest of the doc, so keep that in mind.
In the introduction, include a metaphor for what the project as a whole does. Metaphors are often very useful for helping people connect with projects they aren't familiar with and they give people a framework to insert ideas into for the project.
In the introduction, include a meaningful metaphor for the part of the project this LLD is focused on and where it fits into the larger project. i.e. "The project is like a production line. This section is the quality control worker at the end of the production line that makes sure broken products aren't shipped to customers."
Code snippets are all useful artifacts that are important enough in the eventual code you will write that they should be seen by a wider audience. APIs, DB types, major enums, interfaces between major components, high-touch code with explanations of what it will do, etc. are all important here.
Diagrams should have detailed explanations attached to them that explain their behavior. I do this by filling a diagram with numbered circles and then having a numbered list after the diagram. Readers understand what's in a diagram better than what's in text, so attaching your text to the diagram can be useful for explaining.
If a component has meaningful complexity that cannot be understood immediately in a single sentence, attach a diagram. Diagrams, even simple ones, are much less ambiguous than text.
No low level design survives engagement with the code. No low level design that I have ever written or read has accurately described what the actual implementation was in advance. Note in the document which things are heavy in unknowns, as these are the most likely to change.
If your LLD takes more than two weeks to write, break it down into smaller documents. Large, complex LLDs can often feel overwhelming for both the author and the reader and slowly aggregate errors because they're easier to lose in the shuffle.
Review early and often. Show your LLD to one of the senior team members to gather feedback when it's still in very early stages -- they may have helpful information for potential innovations or how to avoid doing something overly complex. I often make my LLDs available as google docs as I'm writing them in case someone is interested.
The core of your document is the intro, diagrams and code snippets. Most text should be an explanation of useful details, rather than the core of the document itself. A significant portion of the people who will read your document will only have the time look at these and not the rest of the doc, so keep that in mind.
In the introduction, include a metaphor for what the project as a whole does. Metaphors are often very useful for helping people connect with projects they aren't familiar with and they give people a framework to insert ideas into for the project.
In the introduction, include a meaningful metaphor for the part of the project this LLD is focused on and where it fits into the larger project. i.e. "The project is like a production line. This section is the quality control worker at the end of the production line that makes sure broken products aren't shipped to customers."
Code snippets are all useful artifacts that are important enough in the eventual code you will write that they should be seen by a wider audience. APIs, DB types, major enums, interfaces between major components, high-touch code with explanations of what it will do, etc. are all important here.
Diagrams should have detailed explanations attached to them that explain their behavior. I do this by filling a diagram with numbered circles and then having a numbered list after the diagram. Readers understand what's in a diagram better than what's in text, so attaching your text to the diagram can be useful for explaining.
If a component has meaningful complexity that cannot be understood immediately in a single sentence, attach a diagram. Diagrams, even simple ones, are much less ambiguous than text.
No low level design survives engagement with the code. No low level design that I have ever written or read has accurately described what the actual implementation was in advance. Note in the document which things are heavy in unknowns, as these are the most likely to change.
Comments
Post a Comment