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

You're not doing it for them. You're doing it for you. Following your own philosophy (whatever it is) takes an unshakable faith that it is the "right thing to do" even when nobody is watching. Like religion or sobriety, it is a daily struggle to follow what you believe. This is what leaders do.


This is nonsense. Writing elaborate documentation is useless if you already understand your own concepts. Software docs are one thing (comments and readmes) but elaborate documentation meant for knowledge sharing that is never actually read is just a waste of time.

Your sentiment feels more like "dig a hole, it builds character!"


What is "elaborate" here? I write out personal work docs in a wiki complete with links for cross reference and a semantic search engine. Is that elaborate?

I like that I often only need to ask a question once, and that I can delegate answering questions to the docs (where I've published subsections for the rest of the team).

Moreover, as someone with a bachelor's degree in Cognitive Science & Computer Science, I know from the literature and experience that writing things down improves your memory.

If I'm doing it to save my time and expand my memory, then it doesn't matter who else might read it.


Has this been your experience with writing documentation or are you just saying this because it’s obvious.

I only ask because, first and foremost, documentation is for you.


No. Documentation is for the code or the project, for any reader. Proper documentation can be read and understood by anyone that needs to interact with the project. I don't know when it was decided that "documentation is for yourself" but I very much disagree.


Documentation is for yourself in 2 years.




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

Search: