I've mentioned this elsewhere before, but I think it bears repeating. At my company, we have some simple rules:
README describes WHAT your code does.
Comments describe WHY you wrote the code the way you did (intention).
Documentation describes WHAT your code does (in detail) and, more importantly, HOW the user makes it do that. API docs do NOT count here.
API docs may be useful as internal reference for developers, but not for end users. As I've said before, "most API documentation is like teaching someone how to use a toaster by explaining the electrical specifications of the heating element."
(All that from my article [Your Project Isn't Done Yet][1])
I have doubts about your approach to API docs. One of the assessments I am doing, when selecting a piece of software is reviewing the API, which gives me a rough idea about what the software is capable of.
Sure, there may be other reasons to have API docs. The problem is when these are offered as full replacements for end-user documentation...which is exactly what happens in a disgustingly large number of projects.
At the same time, if you're having to read the API docs to figure out what the software does, it means someone didn't actually document it properly.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I've mentioned this elsewhere before, but I think it bears repeating. At my company, we have some simple rules:
READMEdescribes WHAT your code does.Comments describe WHY you wrote the code the way you did (intention).
Documentation describes WHAT your code does (in detail) and, more importantly, HOW the user makes it do that. API docs do NOT count here.
API docs may be useful as internal reference for developers, but not for end users. As I've said before, "most API documentation is like teaching someone how to use a toaster by explaining the electrical specifications of the heating element."
(All that from my article [Your Project Isn't Done Yet][1])
dev.to/codemouse92/your-project-is...
I have doubts about your approach to API docs. One of the assessments I am doing, when selecting a piece of software is reviewing the API, which gives me a rough idea about what the software is capable of.
Sure, there may be other reasons to have API docs. The problem is when these are offered as full replacements for end-user documentation...which is exactly what happens in a disgustingly large number of projects.
At the same time, if you're having to read the API docs to figure out what the software does, it means someone didn't actually document it properly.