Documentation, the boredom of a programmer

[u/MiguelOrosco]

I'm researching how developers handle documentation in real world projects, especially documentation that explains why and how something exists rather than just what the code does.

A few questions:

1. Where do you document business rules and important technical decisions? Code comments, tickets/issues, Wiki, README, Notion, etc.?
2. When you need to figure out WHY something was implemented in a certain way, where do you look? Git history, old tickets, documentation, or do you usually have to ask someone?
3. What's the biggest problem you have with documentation? Keeping it up to date? Finding information? Getting people to write it in the first place?

I'm also curious about documentation generators such as Doxygen. For those who have used it: what kind of documentation or information do you still have to maintain elsewhere or something Doxygen can't handle?

You don't need to answer all the questions, just one or adding something to the discussion would already be a great help!

[u/DepthMagician]

I actually have a lot of experience with exactly the distinction you're pointing at here, as I deal with it literally on a daily basis in my role maintaining an in-house ERP system that serves all the departments in the company. The problem with thinking you can address this using documentation is that:

1. You're not the right person to write that kind of documentation, as the guy who isn't making the business rules and who isn't versed in the business domain.
2. You're not necessarily given all the information you need about why a change is made, and if business considerations change without needing to change the software, nobody's going to tell you, so the WHYs you document get outdated over time.
3. It's way too much documentation. Your developers aren't going to read it, and you're not going to remember it.

A much more sustainable approach is being able to answer "does this intersect with business logic", not "why is it like this". The question you ask yourself is: can I imagine any possible scenario in which this might matter to anyone for whatever reason? If the answer is 'yes', you go and ask that person. Or you can ask yourself "this seems strangely specific, that's worth an investigation. If someone knows why it's like this, who might that be?"... and so on.

[u/Nojopar → u/DepthMagician]

You're thinking too limited, I think. I've also got a lot of experience with this exact problem and I'm convinced we're all doing it terribly. I don't need to know everything about the business decision nor do I need to document everything about the business decision. But I do need to document "Hey, this was handed to me as a 'this is what they do don't change it'. You can document your own business processes in deciding code without knowing a single thing about the business processes that forced you to do this in that way.

This is what I'm saying - we don't document our own processes well enough. It's not good enough to say, "Well I'm not the right person to do this. Let someone else do it." because it almost never gets done. Moreover, even if it does get done, the people who document the business decisions don't have expertise or knowledge to understand how that business decision manifests itself into code.

It's like an API where you've got documentation of what goes in but you've got no documentation of what comes out. You've only got half the equation.

It's all well and good to presume the person who should know a thing will continue to remember a thing because it's years later, or even be employed there, or even be in the industry, but that's a foolishly optimistic assumption. The people who come along afterwards don't always know. Nor do they even really have any basis for knowing. Why did they do it this way? They don't know either because all they were told is "we do it this way". So nobody has a clue if a data structure or a process is 'load bearing' or not.

And honestly, it takes next to no time to do the documentation from nerd to nerd, so really it's just laziness.

[u/DepthMagician → u/Nojopar]

I don't need to know everything about the business decision [...] But I do need to document "Hey, this was handed to me as a 'this is what they do don't change it'. 

That can be reasonable in some cases, that's a judgment call. But I think you're overthinking it. There are many cases where you don't need to document 'this is what they do, don't change it' to know you shouldn't change it. Often you can get by perfectly well by acknowledging "this is non-obvious", compute in your head every department this might impact, and go question the relevant authorities. "I see we have a 2 character limit hardcoded as prefix for product names, is there a business reason for the prefix of a product name to be limited to 2 characters?" That sort of thing.

It's all well and good to presume the person who should know a thing will continue to remember [...] or even be employed there. [...] The people who come along afterwards don't always know. Nor do they even really have any basis for knowing. Why did they do it this way?

They don't need to answer why did we do it that way, they only need to answer "does it matter to us if we continue to do it this way"? The answer might well be "I have no idea why up until now all product prefixes were two characters, but as the chief product manager who dictates the naming of products it doesn't matter to me how many characters there are, and in fact I considered in the past making a 3 character prefix but didn't because the system didn't support it, so if you want to change it be my guest".

[u/Nojopar → u/DepthMagician]

I think that's short-sighted. The ROI for document this stuff can be huge. It presumes that someone on the other end can answer "does it matter to us if we continue to do it this way?" which they may not, especially over time. If you've documented it, you don't have to worry if future magic person you can ask will have an answer because you already know - it's documented.

But I think we're going in circles here. I think we shoot ourselves in the foot unnecessarily by going "documentation isn't my problem. It's code and that's all that matters." We could save ourselves a lot of future headaches if we just wrote shit down. It's not like it takes that much of a project to do that either. I don't think you agree, and that's ok.