4 ms·

I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of o

I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.

colonelxc 6y ago
One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials). Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.
AgloeDreams 6y ago
Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.
gowld 6y ago
Same could be said for code, right? It's a great idea, but in 30 years we've never seen code done well. "Well" is a slippery word.
- commandlinefan 6y ago
  But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
  - etse 6y ago
    In my experience, it’s not the same. Design docs allow a dialogue about the resulting code that code reviews are poorer at or less efficient at. Those conversations have saved us time and gives us confidence that the solution is the best for the problem.
thomascgalvin 6y ago
I think forcing a team to ask these questions is more important than making the document perfect. I've had too many conversations that amounted to "a React front-end, Node backend, Mondo data store is the perfect solution to this and every problem," with no other options chosen. There's also value on having some this kind of documentation when you're bringing on new people. The project I'm currently working on started two years before I got here, and I would love to have a document that explained why, for example, we're using Active Directory instead of some other authentication mechanism.
theptip 6y ago
OP links to a design doc template that implements the ideas it lays out: https://www.industrialempathy.com/posts/design-doc-a-design-doc/ https://www.industrialempathy.com/posts/design-doc-a-design-...
deleted 6y ago
[deleted]

colonelxc 6y ago

One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials). Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.

AgloeDreams 6y ago

Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.

gowld 6y ago

Same could be said for code, right? It's a great idea, but in 30 years we've never seen code done well. "Well" is a slippery word.

commandlinefan 6y ago
But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
- etse 6y ago
  In my experience, it’s not the same. Design docs allow a dialogue about the resulting code that code reviews are poorer at or less efficient at. Those conversations have saved us time and gives us confidence that the solution is the best for the problem.

thomascgalvin 6y ago

I think forcing a team to ask these questions is more important than making the document perfect. I've had too many conversations that amounted to "a React front-end, Node backend, Mondo data store is the perfect solution to this and every problem," with no other options chosen. There's also value on having some this kind of documentation when you're bringing on new people. The project I'm currently working on started two years before I got here, and I would love to have a document that explained why, for example, we're using Active Directory instead of some other authentication mechanism.

theptip 6y ago

OP links to a design doc template that implements the ideas it lays out: https://www.industrialempathy.com/posts/design-doc-a-design-doc/ https://www.industrialempathy.com/posts/design-doc-a-design-...

deleted 6y ago

[deleted]