1. 17

  2. 2

    X. People will not read the docs.

    This depends on the programming language. If the language has one central place for docs (e.g. Go’s godoc.org), people are more likely to read the docs. There will be people who just copy examples, but this can lead to awkward usage (which is bad for everyone).

    It’s worth noting docs and examples don’t need to be separate. godoc.org presents examples right next to the main documentation. You can put examples in the README, but in contrast to a good number of documentation systems, they will become out-of-date.

    Nobody reads them

    This smells like an excuse to not document your library to me.

    X. Peripheral helper features should be cut.

    Could not agree more. Your ParseFromURL will always be missing something (it will be useless to anyone who wants to do caching, progress bars etc.). Flexibility is better than saving 3 lines of code. You also risk reinventing the wheel (I’ve seen cases of HTTP error wrappers in Go RSS parsing libraries).

    X. Micro-efficiency is not important.

    Related: don’t use “better” stdlib-mirroring libraries than what’s in the stdlib (json-iterator for example). These are just unnecessary dependency bloat. Modern binaries are already big enough without 2 copies of the same thing. The stdlib also offers better stability guarantees