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

1 pointsdevstein11mo ago4 comments

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

JohnFen11mo ago

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.

devsteinOP11mo ago

I agree about docs as a tool for thought.

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

JohnFen11mo ago

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.

allears11mo ago

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.

j / k navigate · click thread line to collapse

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

1 pointsdevstein11mo ago4 comments

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

JohnFen11mo ago

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.

devsteinOP11mo ago

I agree about docs as a tool for thought.

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

JohnFen11mo ago

allears11mo ago

j / k navigate · click thread line to collapse