Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

This issue around poor writing skills is something that I've thought/worried about for a while. At some level of seniority (the more junior the better IMO) we expect developers to write design docs. The inability to communicate clearly in those documents is a huge problem. Oftentimes misunderstandings and ambiguities are cleared up at design review, but then never reintegrated into the document, leaving two artifacts, the implementation and the design doc. These obviously drift over time, maintaining correspondence is hard. But when one only ambiguously described the other from the get go, then the documentation is broken. This too is technical debt.

If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.



Consider applying for YC's Winter 2026 batch! Applications are open till Nov 10

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: