So I tried this and it failed miserably.

The documentation became the bible, and although I tried to keep the design goals at the conceptual/logical level the following would happen the moment the implementation started:

1. This is ambigous the docs need updating, please refactor your design 2. This doesn't work as the doc stated why did you get this wrong 3. The requirements have changed you need to update it

The burden to get "everything right" was absolutely lumbered of me, and the document became an easy finger pointing exercise, even if blame wasn't intended by those launching the critique the burden of "owning" the doc and the consequences of the doc was real.

Now there's a good chance that I am just a shit documentation writer, I can accept that, but honestly I feel like for the vast majority of organisations this just falls into another step of the waterfall pattern, which just doesn't work.

How do you handle this? What did I miss?

▲

mtlynch an hour ago | parent [-]

Thanks for reading!

What you're describing sounds like toxic team dynamics rather than something specific to design docs. Do you work effectively with your teammates outside of design docs, or is there similar tension/hostility everywhere?

What you're describing sounds like the design process working as intended (modulo the finger-pointing). The design doc should be unambiguous, and the implementation should match it.

Assuming this isn't just symptoms of a sick team, my other explanation is that your teammates find your deviations from the design doc unexpected. It sounds like you're running into situations where you can't implement the design doc as written, so you're proactively making your own design choices and showing your teammates the implementation. Could you loop your teammates in earlier on before you've implemented the code? Like, "The design docs says we're supposed to use SQLite, but I realized that SQLite doesn't support types the way we expected, so I think we should switch to Postgres for X, Y, and Z reasons."

	▲	CurleighBraces 34 minutes ago \| parent [-]
		Thanks for taking the time to reply, please take my response as earnest attempts to better myself :) So, I think I didn't elaborate on the process enough to get the answers I was looking for. Here's what happened. 1. I would uncover a requirement from the business 2. The conceptual design would be written, high level understanding of the feature etc that was trying to be written 3. Conceptual design would be signed off 4. Logical design would take place ( I think this is basically everything from the Constraints section down in your model ) 5. Logical design would get reviewed and signed off. Now technically everyone could and was encouraged to sign off the logical design, but in reality maybe one other person in the team would, I don't really know the reasons why. Then implementation start, this was usually NOT me but another team member tasked with the design, and this is where the process really started to fall down with the onus being put squarely back on me as to why the design didn't work :) I also actually tried the other approach, implement as much as possible ( because AI fast ) and then reverse engineer the design, but then that very much felt like, what the hell is the point now? I might as well just use the standard code review process. Does that make sense? Sound familiar?