Indeed. Code describes how something is done, and possibly what is done, but it seldom fully describes why something is done, or why code exists in the first place.
The latter is typically the realm of requirements, design documentation, and possibly test plans.
Generating such documentation from code seems quite impossible, or at least wrong.
It is unfortunate that most open source software is lacking in such documentation, giving off bad signals to junior developers.
Edit: not to take away from the product being discussed here, which seems very useful! I am merely supporting the parent here.
> The latter is typically the realm of requirements, design documentation, and possibly test plans.
You forgot one of the biggest spots for "why" documentation... git commit messages, where the point is to say why you made this change. Maybe taking into account the commit messages around the code in question would help.
Yep... and the why of that message is apparent and makes perfect sense for the first commit. If you only ever start projects and never work on them again, that is all you need.
This is a great point, and something we think about. I think to an extent a super smart version of our product could infer intent from the code but there would be definitely something amiss if the author's intent was just never available.
The latter is typically the realm of requirements, design documentation, and possibly test plans.
Generating such documentation from code seems quite impossible, or at least wrong.
It is unfortunate that most open source software is lacking in such documentation, giving off bad signals to junior developers.
Edit: not to take away from the product being discussed here, which seems very useful! I am merely supporting the parent here.