Wiki solution for Dgraph documentation

Hey @minions,

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:
https://wiki.archlinux.org/

This reminds me of documentation of another Linux variant, Gentoo, which I was a fan of back in college:
https://wiki.gentoo.org/wiki/Main_Page

The same goes for another software I’ve using, i3 window manager:
https://i3wm.org/docs/userguide.html

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?

Cheers,
Manish

You aren’t referring to code documentation here right?

ArchWiki looks really good. We could have something like that for

  • Installation instructions
  • FAQ
  • Beginners Guide
  • Contributing Guidelines
  • Channels of communication

Some of these things could go into discourse too, though a Wiki feels more organized.

Yeah, not referring to code documentation which would go through Godoc.

Yeah, that was the initial idea. But, having worked with Discourse, I don’t think it replaces a proper wiki. Google doesn’t index these pages the same way as it does wiki. So, if you search for [test queries dgraph], the top result is GitHub wiki, not our discourse page.

Most people search via Google, and not whatever internal search mechanisms sites might have. That’s a good reason to make it a proper wiki.

On top of that, wikis have pretty amazing structuring between pages, which we could easily use. I was just reading the source code of a page on Gentoo, and for all bash commands, they have a template which renders all of those uniformly. Small things like these help improve the documentation look and feel.

The biggest benefit would be that our community can help maintain it. That’d be worth our efforts to get it kickstarted.

3 Likes

I second the idea of having a separate wiki instead of having things in Discourse. Discourse has its place and that use as a forum for long form discussions will continue. But from a documentation standpoint a standalone wiki makes sense.

How do we make sure the wiki is integrated well with our website and Github?

It probably won’t. Different system. But, we can make it look similar, with our customized theme or something. And ensure there’s a link from our site to the wiki and vice-versa.

I doubt it would be an issue. In fact, we can keep it simple and focus purely on the content.

To repeat the same example, Arch Linux’s wiki doesn’t look great, it just looks efficient.

2 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.