17 ms·

Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fai

Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.

Aperocky 6y ago
> I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.
- eitally 6y ago
  I think -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders to certify whether the guesses and assumptions made by developers are correct or not. Since in many cases the business owner(s) had never actually considered many of the edge cases (stupid, basic example: previous company required CFO approval of all international travel requests. Tool was built with this logic. No one considered how to handle it when the CFO was unavailable for whatever reason, so the first time the CFO went on vacation it created all kinds of stupid chaos while a manual process was created.), flexible logic paths aren't designed into workflow apps. Similarly, for reporting/BI tools, there are frequently gaps between the answers executives want to glean from the data, and the business processes the ultimately result in the data creation. Because of this, nearly all reports are faulty, but unless you're close enough to the processes you don't have explainability and uninformed business decisions can result. Ditto from CRUD apps, where form validation rules can be insanely complex for stupid reasons, with the result being the data entered is impossible to use. Apologies for the diatribe. Big fan of design docs, but an even bigger fan of software engineering cultures that focus on simplicity and usability, rather than being everything to everyone (or worse, being a pet project of an exec who changes their mind every quarter about how things should work).
  - Aperocky 6y ago
    Yeah that read like a lot of baggage, some of the term I'm not even familiar with (SQA, DD?) As it stands now, we take high level feature design docs from PM, and turn them into service. Everything between that, resources, development, operations are handled entirely in team where everyones title is SDE. This placed a lot of communication, writing, designing on us but I'm not complaining.
- sanderjd 6y ago
  I think this myth comes about because early in peoples' careers, the expectations of the job are a lot more focused on writing code to execute a vision defined by someone else. It is easy to get the impression from this that writing code is viewed as the most important part of the job. But in reality, it works this way because the opposite is actually true, the more important non-coding parts of the job are being entrusted to more experienced people (often to their chagrin, because writing code is way more satisfying and fun).
jakevoytko 6y ago
> Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it I think this is a major benefit of design docs - they are a way to extend your engineering influence beyond your own individual output. If you write a design, and your design allows you and three other engineers to coordinate your efforts, then your engineering output is now "I coordinated a team to build something that any of us couldn't have written individually." This dovetails nicely with your next point - uncovering blockers as early as possible is critical when coordinating a bunch of entities. Project plans are usually written on the assumption that every task will succeed, but there may be extra tasks added. If a task cannot be completed / you need to redesign something / etc, this will suddenly bring the work of N engineers to a halt. The earlier you successfully split the work into a series of known unknowns and implementation tasks, the better the project will go in general.
- mikepurvis 6y ago
  > ... uncovering blockers as early as possible is critical when coordinating a bunch of entities. I think the challenge for me has always been that the "uncover blockers" piece means building one or more small prototypes to prove out the capabilities of the dependencies, check feasibility, etc. So the building of these prototypes occurs prior to or in parallel with the authoring of the design doc, but then at a certain point they get paused so that the design doc can be completed and reviewed, and then picked up again when it's time for the "real" implementation to occur. But pausing there takes discipline, since it ideally happens at the exact moment when all the main blockers have been cleared away and it is maximally tempting to just step on the gas and start into the work of cobbling the prototypes together into the project.
  - mLuby 6y ago
    It's also important to set clear expectations with stakeholders who have seen the prototype and may think the project is 90% done, when in fact there's still 90% more to go in making that prototype production-ready.
learc83 6y ago
>If code is the bricks and mortar, then these docs are the blueprints. That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints. You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens. The problem is that the only way to get to that level of specificity is with code. Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.
- cameronbrown 6y ago
  I mean, you're right... but the goal of an analogy isn't to be perfect, but to be a rough mental model to quickly express a concept. I think it's fine. Different jobs require different levels of abstraction and design docs fulfil that role for software engineers.
  - learc83 6y ago
    Yes models can be helpful even if they aren’t perfect. But not only is this one too far off to be useful, it does more harm than good. The expectations that happen when people (specifically managers) start thinking of design docs as blueprints, software architects as architects, and developers as builders are downright dangerous.
    - sgt-serverless 6y ago
      Dangerous seems a bit extreme. If developers aren't builders, then what are they?
    - DEADBEEFC0FFEE 6y ago
      Models are always imperfect.
  - shuntress 6y ago
    That is true but if the analogy is too imperfect then it won't express the right concept. A bad analogy is like a leaky screwdriver.
sethammons 6y ago
At work, we call them blueprints :). A fantastic way to get early feedback before writing any code, especially important for junior teams who may forget to think about failure cases and operability.
everlost 6y ago
My experience has been that writing the design doc is not as controversial, as much as the review process. Does anyone have any insights on how to make the reviews more constructive + quicker?
- eckesicle 6y ago
  My thoughts on this matter: 1. Start with defining the problem you want to solve and identify the stakeholders. Then meet each stakeholder 1-1 and get approval. 2. Propose an API. Then meet 1-1 again for approval. 3. Make a high level arch diagram. Seek approval again. 4. Proceed with actually writing the design doc and begin the formal and official review. Points 1-3 could be done in a week if planned well and will make the design doc a lot less controversial and get you through the review process quicker
- whoevercares 6y ago
  The review process has a human factor in it IMO. I’ve seen many designs get scratched just because “this should be done and designed by Team B rather than you”. Problem is that could come late. Sometimes it could be a career development bummer for the engineers who invest a lot into the design.
  - etse 6y ago
    But isn’t that better than code (especially if working) that gets scratched? I think designs that are scratched indicate you don’t understand the value you contribute to your company (or that management sees in you) which should be the root concern for the career development.
    - whoevercares 6y ago
      Yea, designs are cheaper then actual implementation. It’s not always the case that the engineer doesn’t understand the value but most times it’s about the management/PM can’t get things finalized over a long period of time. Sometimes I feel it’s just politics in some cases. Don’t you ever need to fight to do some high visibility work?
draw_down 6y ago
What engineers actually do is determined by the incentive structure they work in. If shipping is prioritized all the time above everything else, one of the things that will suffer is documentation. If people get promoted in spite of not doing a good job of documentation, now you know why it doesn't happen.
thehappypm 6y ago
In a much more real sense, the code itself is the blueprint. The compilers/interpreters lay the bricks and mortar for us.
rogy 6y ago
One thing I've noticed as I've got more experienced was that when I started out, a PM or senior engineer would give me a task to do. I achieved the outcome, mostly with bad to average code that slowly improved over time. When I finally understood the domain to make bigger scoped decisions, I started doing design docs beforehand and my code continued to improve greatly. Now when assigning out work to more junior engineers I find myself giving them a high-level design doc, with some detail missing, they deliver higher quality work than I did at that stage, and they also seem to upskill faster. This however depends on me making the right decisions at this stage, which is not always the case, so not fool-proof but an overall software quality improvement has definitely occured.
- musingsole 6y ago
  Blessed are those who provide fully (or reasonably) spec'ed work to juniors trying to piece everything together against a book they read once.
taeric 6y ago
This often betrays an understanding of blueprints to builds that just isn't true. The blueprint of simple things is how they are built. Even complicated things, this will be roughly true for new things. For old things and complicated things, though, they were how things could be attempted to be built. And with the builder being someone else, there had to be an audit from the build to the blueprint, if you really want confidence in that statement.
maps7 6y ago
I work in an agile/scrum team. Do you have any experience in tracking the design doc work in this type of environment? It's hard to estimate how long a design doc would take since investigation into the solution and conversations with stakeholders could expand it.
- gowld 6y ago
  If your estimates matter, you are doing agile wrong. Reserve some time, do some work, repeat.
  - maps7 6y ago
    But you have to estimate to know how much work you'll fit into a sprint, right? Nothing happens if the estimate is wrong really but it helps fit an amount of work into a period of time
LdSGSgvupDV 6y ago
How did you balance the coding and documenting for totally new product when there are rapid iterations?

Aperocky 6y ago

> I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.

eitally 6y ago
I think -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders to certify whether the guesses and assumptions made by developers are correct or not. Since in many cases the business owner(s) had never actually considered many of the edge cases (stupid, basic example: previous company required CFO approval of all international travel requests. Tool was built with this logic. No one considered how to handle it when the CFO was unavailable for whatever reason, so the first time the CFO went on vacation it created all kinds of stupid chaos while a manual process was created.), flexible logic paths aren't designed into workflow apps. Similarly, for reporting/BI tools, there are frequently gaps between the answers executives want to glean from the data, and the business processes the ultimately result in the data creation. Because of this, nearly all reports are faulty, but unless you're close enough to the processes you don't have explainability and uninformed business decisions can result. Ditto from CRUD apps, where form validation rules can be insanely complex for stupid reasons, with the result being the data entered is impossible to use. Apologies for the diatribe. Big fan of design docs, but an even bigger fan of software engineering cultures that focus on simplicity and usability, rather than being everything to everyone (or worse, being a pet project of an exec who changes their mind every quarter about how things should work).
- Aperocky 6y ago
  Yeah that read like a lot of baggage, some of the term I'm not even familiar with (SQA, DD?) As it stands now, we take high level feature design docs from PM, and turn them into service. Everything between that, resources, development, operations are handled entirely in team where everyones title is SDE. This placed a lot of communication, writing, designing on us but I'm not complaining.
sanderjd 6y ago
I think this myth comes about because early in peoples' careers, the expectations of the job are a lot more focused on writing code to execute a vision defined by someone else. It is easy to get the impression from this that writing code is viewed as the most important part of the job. But in reality, it works this way because the opposite is actually true, the more important non-coding parts of the job are being entrusted to more experienced people (often to their chagrin, because writing code is way more satisfying and fun).

jakevoytko 6y ago

> Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it I think this is a major benefit of design docs - they are a way to extend your engineering influence beyond your own individual output. If you write a design, and your design allows you and three other engineers to coordinate your efforts, then your engineering output is now "I coordinated a team to build something that any of us couldn't have written individually." This dovetails nicely with your next point - uncovering blockers as early as possible is critical when coordinating a bunch of entities. Project plans are usually written on the assumption that every task will succeed, but there may be extra tasks added. If a task cannot be completed / you need to redesign something / etc, this will suddenly bring the work of N engineers to a halt. The earlier you successfully split the work into a series of known unknowns and implementation tasks, the better the project will go in general.

mikepurvis 6y ago
> ... uncovering blockers as early as possible is critical when coordinating a bunch of entities. I think the challenge for me has always been that the "uncover blockers" piece means building one or more small prototypes to prove out the capabilities of the dependencies, check feasibility, etc. So the building of these prototypes occurs prior to or in parallel with the authoring of the design doc, but then at a certain point they get paused so that the design doc can be completed and reviewed, and then picked up again when it's time for the "real" implementation to occur. But pausing there takes discipline, since it ideally happens at the exact moment when all the main blockers have been cleared away and it is maximally tempting to just step on the gas and start into the work of cobbling the prototypes together into the project.
- mLuby 6y ago
  It's also important to set clear expectations with stakeholders who have seen the prototype and may think the project is 90% done, when in fact there's still 90% more to go in making that prototype production-ready.

learc83 6y ago

>If code is the bricks and mortar, then these docs are the blueprints. That analogy falls apart quickly. Design docs aren’t specific enough to be analogous to blueprints. You can give a set of blueprints to 3 different construction firms and get fundamentally the same building. Try giving design docs to 3 different development shops and see what happens. The problem is that the only way to get to that level of specificity is with code. Design docs are closer to something a city planner would produce than to something an architect or civil engineer would, and they should be treated accordingly.

cameronbrown 6y ago
I mean, you're right... but the goal of an analogy isn't to be perfect, but to be a rough mental model to quickly express a concept. I think it's fine. Different jobs require different levels of abstraction and design docs fulfil that role for software engineers.
- learc83 6y ago
  Yes models can be helpful even if they aren’t perfect. But not only is this one too far off to be useful, it does more harm than good. The expectations that happen when people (specifically managers) start thinking of design docs as blueprints, software architects as architects, and developers as builders are downright dangerous.
  - sgt-serverless 6y ago
    Dangerous seems a bit extreme. If developers aren't builders, then what are they?
  - DEADBEEFC0FFEE 6y ago
    Models are always imperfect.
- shuntress 6y ago
  That is true but if the analogy is too imperfect then it won't express the right concept. A bad analogy is like a leaky screwdriver.

sethammons 6y ago

At work, we call them blueprints :). A fantastic way to get early feedback before writing any code, especially important for junior teams who may forget to think about failure cases and operability.

everlost 6y ago

My experience has been that writing the design doc is not as controversial, as much as the review process. Does anyone have any insights on how to make the reviews more constructive + quicker?

eckesicle 6y ago
My thoughts on this matter: 1. Start with defining the problem you want to solve and identify the stakeholders. Then meet each stakeholder 1-1 and get approval. 2. Propose an API. Then meet 1-1 again for approval. 3. Make a high level arch diagram. Seek approval again. 4. Proceed with actually writing the design doc and begin the formal and official review. Points 1-3 could be done in a week if planned well and will make the design doc a lot less controversial and get you through the review process quicker
whoevercares 6y ago
The review process has a human factor in it IMO. I’ve seen many designs get scratched just because “this should be done and designed by Team B rather than you”. Problem is that could come late. Sometimes it could be a career development bummer for the engineers who invest a lot into the design.
- etse 6y ago
  But isn’t that better than code (especially if working) that gets scratched? I think designs that are scratched indicate you don’t understand the value you contribute to your company (or that management sees in you) which should be the root concern for the career development.
  - whoevercares 6y ago
    Yea, designs are cheaper then actual implementation. It’s not always the case that the engineer doesn’t understand the value but most times it’s about the management/PM can’t get things finalized over a long period of time. Sometimes I feel it’s just politics in some cases. Don’t you ever need to fight to do some high visibility work?

draw_down 6y ago

What engineers actually do is determined by the incentive structure they work in. If shipping is prioritized all the time above everything else, one of the things that will suffer is documentation. If people get promoted in spite of not doing a good job of documentation, now you know why it doesn't happen.

thehappypm 6y ago

In a much more real sense, the code itself is the blueprint. The compilers/interpreters lay the bricks and mortar for us.

rogy 6y ago

One thing I've noticed as I've got more experienced was that when I started out, a PM or senior engineer would give me a task to do. I achieved the outcome, mostly with bad to average code that slowly improved over time. When I finally understood the domain to make bigger scoped decisions, I started doing design docs beforehand and my code continued to improve greatly. Now when assigning out work to more junior engineers I find myself giving them a high-level design doc, with some detail missing, they deliver higher quality work than I did at that stage, and they also seem to upskill faster. This however depends on me making the right decisions at this stage, which is not always the case, so not fool-proof but an overall software quality improvement has definitely occured.

musingsole 6y ago
Blessed are those who provide fully (or reasonably) spec'ed work to juniors trying to piece everything together against a book they read once.

taeric 6y ago

This often betrays an understanding of blueprints to builds that just isn't true. The blueprint of simple things is how they are built. Even complicated things, this will be roughly true for new things. For old things and complicated things, though, they were how things could be attempted to be built. And with the builder being someone else, there had to be an audit from the build to the blueprint, if you really want confidence in that statement.

maps7 6y ago

I work in an agile/scrum team. Do you have any experience in tracking the design doc work in this type of environment? It's hard to estimate how long a design doc would take since investigation into the solution and conversations with stakeholders could expand it.

gowld 6y ago
If your estimates matter, you are doing agile wrong. Reserve some time, do some work, repeat.
- maps7 6y ago
  But you have to estimate to know how much work you'll fit into a sprint, right? Nothing happens if the estimate is wrong really but it helps fit an amount of work into a period of time

LdSGSgvupDV 6y ago

How did you balance the coding and documenting for totally new product when there are rapid iterations?