Hacker News new | past | comments | ask | show | jobs | submit login

I write copious documentation for everything I touch. My colleagues do not bother to read them, nor do they try to learn from my practices. I continue to do so, everywhere I go, because I design my applications by writing documentation first, or alongside my code. It helps me think. I do not think that tools are necessarily the problem. I use README.md files mostly after trying to use Sphinx and Notion. This has a very low entry point. But they do not care. They insist on using one time hacks and never documenting things, even Root Cause Analyses.

Like others have said here, we need ways to improve and build a culture of reading and writing documentation. Our CTO says he wants to build this, but there's some disconnect.




If you don't have the skills, power, or desire to improve the culture where you work, and it consistently bothers you, then go work somewhere that's already closer to what you want.

Amazon and Google are good examples of companies that make heavy use of written design documentation and post-mortems.


Any ideas on how one might “build a culture of reading and writing documentation”?




Consider applying for YC's Spring batch! Applications are open till Feb 11.

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

Search: