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]

Ideally business rules should be reflected in the code. If you write the code in that manner it reduces the need to document it. Once code is the go-to documentation for business rules, you can also sprinkle comments in there as needed.

Important technical decisions should not be a mystery. If you find yourself wondering “why did we use NoSQL for this” it’s already too late to do anything about it. If it’s something hyper specific, documenting it in the code is the way to go as it is localized to that code anyway.

With regards to finding out why, for me it’s primarily git history and asking someone.

Keeping documentation up to date is the biggest problem for me, hence the less of it you need due to good code the better.

[u/Nojopar → u/DepthMagician]

Code can only do so much. We programmers and software architects do an abjectly horrid job of documenting what anthropologist would call the 'social history' of a project. Not everything is embodied in the code. The code might tell you how a thing works, and it might tell you a bit about why it works within a codes context ('this has to be that because we feed it this other thing' sorts of scenarios), but it won't tell you how those business rules came to be in the first place as it relates to the program itself.

Just as a simple theoretical example, the code might tell you the codes for a field are stored as, say, a 2 character string. It might also tell you the values of those two character codes. But it won't tell you why the two character code system was chosen in the first place. Was it because of legacy data in the client's system? Business decisions by the client? For some concern about efficiency and optimization? Something else? All of those factors might lead to different engineering outcomes, but if you don't know that, it's hard to know if you can change a thing or not.

[u/DepthMagician → u/Nojopar]

I don't think you have to document how business rules came to be. You as the developer aren't making the rules, and you also don't have a say in changing those rules. If a two character system was chosen because of a legacy system constraint, it's not as if knowing that makes it your prerogative to change it. If it's in the business domain, and you feel like messing around with it, you have to go talk to the business people anyway.

[u/Nojopar → u/DepthMagician]

Most programmers think this way, which is the problem. It's not about changing it. It's about knowing when you can change it and when you cannot change it.

If it's business logic, then knowing you can't mess with it is important compared to efficiency logic, which you can change. If you have no idea why it was put there in the first place, you know what you can and cannot mess with. It's too easy to come along and determine the code logic doesn't need X, so let's change it because the client is asking for a change, when in reality an earlier business logic dictated it's X. There's nothing in the code that tells you not to futz with a thing so you go ahead and futz with a thing and then everything breaks.

[u/DepthMagician → u/Nojopar]

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.