Comment by CurleighBraces | Hacker News Reader

Comment by CurleighBraces | Hacker News Reader

Parent Full thread

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?

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."

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?

It's hard to say without knowing what things are like at the company/team you work for, but I can say the things you're describing sound unusual to me.

Most significantly, it's strange for the person writing the design doc not to be the person implementing the code. This is asking for trouble because there's a principal-agent problem[0], and also there's bound to be signal lost in the handoff between designer and implementer. It's not so unusual for the design doc author to work with a team on implementation, but they'd still be actively involved in implementation, which sounds different from what you're describing.

I've also never heard of this separation between a conceptual design doc and a logical design doc. I've been on teams where the product manager writes a UX-focused spec, and then the dev writes a technical-focused spec, but I've never heard of a conceptual vs. logical spec.

Does the org have a strong engineering culture in other ways? Like automated tests, automated deploys, automated monitoring/alerting, useful code reviews? Because the easiest answer is that you're in an org with poor software engineering practices, or at least weak documentation culture, and the design review process you're experiencing is there for historical or political reasons rather than engineering reasons.

[0] https://en.wikipedia.org/wiki/Principal%E2%80%93agent_proble...

Well, there's a fascinating insight, most orgs I've ever worked for have had the documentation produced by someone else and them implemented by the developer.

For instance the enterprise architect/solutions architect ( or whatever job title is fashionable at the time ) would write the document and then send it over to the development team and obviously that wouldn't work.

I actually adopted the conceptual/logical design from two ex Hewlett Packard engineers/architects who introduced the idea to me, probably some twenty years ago now!

Yep we're strong in many other ways, but finding the transition to AI challenging :)

Reviews have somewhat turned into, I send you the output from my AI agent of choice, and you tell your AI agent of choice to fix it :)

Thanks again for the time taken to reply :) It is appreciated.

Reply on news.ycombinator.com