128
github
7y

Documentation is indeed crazy

Source: Instagram

Comments
  • 3
    @jAsE I can feel you.

    Everyone wants it to be good.
  • 1
    Everytime I've written actual docs and not just generated markdown ..

    I get told it would be better if I just left it out and pointed to the test suite..
  • 1
    @lotd It depends.
    The easiest way if you are running out of time is to have minimal docstring.
  • 1
    @jAsE that's true. I'm no exception.

    @github example of a minimal doc string
  • 1
    @lotd not ideal. But nowadays, I try to always have a single line description, params with description and the return object.

    I haven't started to build APIs used by external Devs, but yes, I need a lot to improve documentation skills too.

    Apart from docstring, I do write wiki(during my personal free time) on how to use it and how to setup if someone wants to contribute.
  • 4
    To me it’s like this:

    documentation is like sex

    When it’s good you know it’s good

    When it’s bad you just want to go somewhere and do it over by yourself.
  • 3
    @easyrhino You are pretty independent in that case. 😂
  • 1
    Unless it's Microsoft documentation, then I'd rather have nothing.
Add Comment