4 ms·

What's wrong with design docs being on a whiteboard? Not every company has time to painstakingly draw pretty UML diagrams in Figma when there are features that

What's wrong with design docs being on a whiteboard? Not every company has time to painstakingly draw pretty UML diagrams in Figma when there are features that need to be built!

brazzy 4y ago
A whiteboard is a great tool to quickly iterate towards a shared understanding of the design at that point in time. But if you take a photo of it and think you're done with documenting your design, you A) lose most of the context of the decisions that were made to arrive at that design. And B) have ensured that your documentation will get outdated and become useless pretty soon. You've basically decided not to have design documentation but filled yourself into believing that you do. If you are serious about documenting software design to help future developers understand the system, you really do need those diagrams in a digital, easily updateable format and with textual explanations of the underlying decisions. And if doing that seems more work than it's worth, do it anyway, just with less details.
alexjplant 4y ago
You joke, but I once worked on a team where nobody was able to point me to any coherent high-level documentation of what the system actually _did_... they all just walked around referring to it by some proprietary name as though you were some type of misinformed dunderhead for not understanding them. It took two hours of a manager talking and filling up a wall-sized whiteboard for me to discover that it was just a hideously over-engineered amalgamation of a CDN and document repository. If they'd had a diagram, README, or had even been able to give me the one-sentence overview then I suspect that the project's head count and productivity would have looked much different. This is all to say that if you 1) invent novel terminology for things that already exist, 2) don't document anything, and 3) run your team like a high school clique then you never have to worry about finding yourself out of a job. Thankfully my current gig has loads of video training and an interactive dictionary for proprietary terms in an attempt to combat this.
- AtlasBarfed 4y ago
  And all the silicon valley layoffs, likely filled to the brim with people that conscienciously documented their replaceability for their employer, will look at that "high school clique" and remark "that's how you deal with sociopathic management". Yeah, eventually management will nuke the whole division, but at least it provides those with jobs a bit more runway. How much of the bemoaning of such adversarial tactics by engineers themselves is simply annoyance at what it causes them at their jobs, or the fact they have internalized pro-management propaganda?

What's wrong with design docs being on a whiteboard? Not every company has time to painstakingly draw pretty UML diagrams in Figma when there are features that need to be built!

brazzy 4y ago

A whiteboard is a great tool to quickly iterate towards a shared understanding of the design at that point in time. But if you take a photo of it and think you're done with documenting your design, you A) lose most of the context of the decisions that were made to arrive at that design. And B) have ensured that your documentation will get outdated and become useless pretty soon. You've basically decided not to have design documentation but filled yourself into believing that you do. If you are serious about documenting software design to help future developers understand the system, you really do need those diagrams in a digital, easily updateable format and with textual explanations of the underlying decisions. And if doing that seems more work than it's worth, do it anyway, just with less details.

alexjplant 4y ago

You joke, but I once worked on a team where nobody was able to point me to any coherent high-level documentation of what the system actually _did_... they all just walked around referring to it by some proprietary name as though you were some type of misinformed dunderhead for not understanding them. It took two hours of a manager talking and filling up a wall-sized whiteboard for me to discover that it was just a hideously over-engineered amalgamation of a CDN and document repository. If they'd had a diagram, README, or had even been able to give me the one-sentence overview then I suspect that the project's head count and productivity would have looked much different. This is all to say that if you 1) invent novel terminology for things that already exist, 2) don't document anything, and 3) run your team like a high school clique then you never have to worry about finding yourself out of a job. Thankfully my current gig has loads of video training and an interactive dictionary for proprietary terms in an attempt to combat this.

AtlasBarfed 4y ago
And all the silicon valley layoffs, likely filled to the brim with people that conscienciously documented their replaceability for their employer, will look at that "high school clique" and remark "that's how you deal with sociopathic management". Yeah, eventually management will nuke the whole division, but at least it provides those with jobs a bit more runway. How much of the bemoaning of such adversarial tactics by engineers themselves is simply annoyance at what it causes them at their jobs, or the fact they have internalized pro-management propaganda?