3 ms·
If I was an eccentric billionaire, I'd reward good documentation with an open source doc prize. It's so difficult to impress upon some people just important do
by bloopernova 7y ago
If I was an eccentric billionaire, I'd reward good documentation with an open source doc prize.
It's so difficult to impress upon some people just important documentation is. And when they do it, they half-ass it by copying stuff from source code and not adding any context.
- gigatexal 7y ago+100 to this. I’ve become a cheerleader for some projects just because the documentation was so good that it was easy to get started. It’s how I became a ZFS zealot among other things.
- voltagex_ 7y agoOT: where do you find the good ZFS documentation? Googling always seems to turn up Oracle's documentation, which may not match what's in FreeBSD or ZFS-on-Linux
- stock_toaster 7y agoThe zfs man pages (at least on FreeBSD) are actually pretty decent for finding command usage. The FreeBSD handbook[1] covers some typical usages. [1]: https://www.freebsd.org/doc/handbook/zfs.html https://www.freebsd.org/doc/handbook/zfs.html
- gigatexal 7y agoTo be fair -- the docs for ZFS via the manpage are great but I found a lot of help also from forums of likeminded folks -- ServeTheHome (https://servethehome.com https://servethehome.com) is where I got hooked. And then there are countless GitHub projects where the README.md file, which is usually first thing I read, that is super well documented and written for the noob (imo). The best example of that so far, especially for someone like me just getting started with the framework, is the gin Golang http framework: (https://github.com/gin-gonic/gin https://github.com/gin-gonic/gin) -- that readme is full of useful examples.
- antpls 7y agoGoogle does something similar: https://developers.google.com/season-of-docs/docs https://developers.google.com/season-of-docs/docs