I’ve been using Arch Linux over the past weeks and have been really impressed with it’s documentation. It’s just stellar! And a great example of how documentations should be:
This reminds me of documentation of another Linux variant, Gentoo, which I was a fan of back in college:
The same goes for another software I’ve using, i3 window manager:
I think having a well detailed and clear documentation would be absolutely crucial for Dgraph’s long term adoption. Arch Linux guys have put a lot of effort on maintaining and improving their documentation, and when I’m struggling with issues, it’s my default go-to place. In fact, that’s an understatement.
For any software that I use, whether or not I use Arch, Google points to Arch Wiki – because they’ve done a really great job of documenting installation and configuration instructions for almost all useful linux softwares – whether or not these softwares had docs of their own.
The one thing I find in common with both Arch and Gentoo is that they use MediaWiki. This is the wiki system which Wikipedia uses.
Generally, I favor solutions which allow me to edit stuff via markdown using my favourite editor (vim), but I think in this case, the idea is that our community would help us fix issues with our wiki as we go along. So, while we might be the prime creators, we won’t be the only maintainers of the wiki pages.
And for those reasons, I’m thinking that we install MediaWiki (or some other equivalent solution) for Dgraph, and start using it to add the much documentation.
I don’t personally like Github Wiki. It feels restrictive. I think following in the footsteps of other successful open source technologies with active communities is a better solution.
What do you guys think?