HN Explorer

Ask HN: Given the choice, would you write documentation if you didn't have to?

1 points by devstein ↗ HN
I personally find writing internal documentation very monotonous even though I know it's important.

I'm curious if you were told you could have decent internal documentation automatically generated for you that were good enough, but not competitive w/ human maintained docs.

Would you still take the effort to write your own documentation?

4 comments

[ 1080 ms ] story [ 72.3 ms ] thread
allears
Nope. Writing documentation for myself does two important things. First, it helps me clarify my own thinking, often leading to better code. Second, when I inevitably have to modify or maintain my own code months later, it reminds me of my original intent.
JohnFen
Yes, I would. Writing documentation is an integral part of my development process. It's part of how I plan and think. It's not optional unless the project is simple.
devstein
I agree about docs as a tool for thought.

What about the other side of docs, keeping them up to date?

JohnFen
I don't really see that as a different thing. The docs and comments guide you when it comes to doing maintenance, so it's natural to use them to plan and think about the needed changes. They get updated almost as a side effect.

I guess the mindset I have internalized is that I don't really see doc writing/updating as a separate thing from coding. I do it out of habit and without really being aware of it. Or, more likely, I've just been doing this a very long time and have deeply ingrained habits.