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

You should also take into consideration that reading docs takes time. If a different designer (marketing guy) is supposed to do a simple 30m task (draft that Merry Christmas popup real quick), they probably won't get those extra 5 hours to read the docs


And after those 5 hours you spend another 5 hours beating your head against the wall until you finally realize the docs are out of date.

Stale docs are worse than no docs. IME (at non-FAANG, non-tech darling companies) docs *always* go stale pretty quickly. No one wants to take on the thankless, unbudgeted task of keeping the docs up-to-date, or browbeating all the other devs to update the docs when they make changes.

The only docs I push for are stuff like swagger where the documentation is also living code. Otherwise I say just put it in the readme, and every repo has a clear owner responsible for keeping that readme up-to-date as necessary.




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

Search: