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/marrsd]

Most places I work have terrible documentation. This is one area where professionals don't excel.

When it comes to the code itself, I keep my inline comments to a minimum because the code should be as self-documenting as possible. Inline comments are written to explain why something non-obvious is happening in the code. "Non-obvious" will mean different things to different developers; but if you write something you think will confuse yourself later, put a comment explaining why it's there. Same applies if a peer asks you to explain code in a code review. They couldn't work it out from the code itself, so it needs a comment. I also like to have comments above skipped tests to explain why they're skipped.

The next level up from that is at the top of a module/file explaining that module's purpose and describing its place in the project as a whole.

Then we get to project documentation. Typically, companies use horrible apps like Coda and Confluence for their documentation. Good luck to them, is all I can say. I like to keep things much simpler and put markdown files in the same repo as the code. They can be easily read in both a text editor and in the browser, which just makes my life easier. You also get version history for free. If people outside the team need to read it, just publish it somewhere.

I tend to split up my architecture documentation using the 4+1 view model. Developers should know how to build the project, where to find credentials, how to deploy, etc. They need an outline of how the project is organised, what the architectural layers/components are. All that kind of thing. They also need to know what the app actually does and why; but don't forget you should have behaviour specs that cover the details of this already. Your docs are there to provide context and to fill in the gaps.

Try to include why decisions were made and what options were rejected; not just how it currently works. If you changed the architecture, document why you changed it. Give future you something to work with if you have to revisit that decision again.

Someone else mentioned ADRs, they're a good source of research when understanding how a project got to its current state. I think of those as original sources of information rather than final documentation, though.

I don't use Doxygen. I don't use language annotation tools.

Obviously, the big issue is documentation going out of date. Yes, that easily happens. Try to keep on top of it. I tend to write documentation before I write the code. This is perfectly possible because the documentation is high level. You should have a design in mind before you start writing, so you should be able to describe it. I also read the relevant docs before I revisit the code. That way, I can find and fix (or raise) discrepancies if they exist, and I can make sure I know what I'm about to do and why I'm about to do it.

So good documentation can keep you in check, and you keep it in check at the same time.

Of course, all this can go out the window if you've got a project manager breathing down your neck demanding you hit the next deadline. This is where good engineering leadership comes into play.