News for hackers. Stuff that matters.
Re:If someone’s having to read your docs, it’s not “simple” by feoren on Monday June 07, 2021 @01:04AM (#27419167)
If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever!
Re:If someone’s having to read your docs, it’s not “simple” by atoav on Monday June 07, 2021 @03:26AM (#27419971)
Oh no worries I have written enough documentation. And you are right: writing good documentation is never done, because the thing you are documenting is never done and you can always fine tune the texts that you have written.

But more often than not you will find auto generated documentation where you see nothing on the first page, nothing explaining what that library can do, can't do, is intended to be used for, is not intended to be used for, some usage example how to get started etc.

Instead you will find a half page in some obscure class documentation that seems to be addressed to the dev themselves instead of to any outside audience.

What I mentioned above doesn't have to take long. You built the library. If you cannot write a simple example of how to use it within 5 minutes you probably should rewrite that library before publishing it. Integrate that example into your tests and now you even know when it will fail.