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

#1

Post by devstein » Tue, Apr 01, 2025, 11:50 PM UTC

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?

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

#2

Post by allears » Wed, Apr 02, 2025, 12:07 AM UTC

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.

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

#3

Post by JohnFen » Wed, Apr 02, 2025, 12:57 AM UTC

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.

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

#4

Post by devstein » Wed, Apr 02, 2025, 1:00 AM UTC

JohnFen wrote: post #3

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.

I agree about docs as a tool for thought.

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

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

#5

Post by JohnFen » Wed, Apr 02, 2025, 1:07 AM UTC

devstein wrote: post #4

JohnFen wrote: post #3

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.

I agree about docs as a tool for thought. What about the other side of docs, keeping them up to date?

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.