Before diving into some critical feedback, let me preface by saying dgraph is a very exciting database and, in general, I really love the (substantial) work so far.
I’ve been working on learning dgraph off-and-on for the past few weeks and so far I’ve found the documentation to be…lacking. Part of it is that I, personally, find DQL to be non-intuitive so that means I’m relying on the docs much more than I would when writing, say, Neo4j’s Cypher (which I generally find to be intuitive) or Firebase’s Firestore (which, admittedly, is a much less powerful query language than DQL but is also intuitive for me). But separately I do think the documentation just isn’t well thought out at this point.
This issue is a good example both because the “correct” DQL is highly counterintuitive to me and also because I don’t think that using DQL and GraphQL APIs together is well described in the docs (which apparently involves special considerations).
- Edit: I found that there is a section of the docs that describe using DQL and GraphQL together, but it’s called “GraphQL on Existing Dgraph”. What about someone who’s creating a new instance of dgraph that uses both DQL and GraphQL? So long as there are things you can only do with one API vs the other, I expect many apps will use both APIs. This is a pretty direct example of poor documentation. For example, renaming this section to “Using both DQL and GraphQL” would be an improvement and linking to this section from both the GraphQL and DQL docs, since you can’t predict where someone will start, would be another improvement (not sure why this concept is only mentioned in the GraphQL section–I generally find the GraphQL section to be more intuitive so I’ve been spending most of my time in the DQL section).
Considering how much time and energy must have been spent to getting dgraph to this point, it really seems like you’re shooting yourself in the foot by not spending more time on the documentation.
As another example, I’d love to never need to learn RDF when learning dgraph. I’m already spending time learning a new, proprietary query language (DQL), I’d rather just stick with JSON since I’m not already familiar with RDF. And dgraph seems to support my choice to do this. Unfortunately, the documentation doesn’t support this choice as the docs often default to RDF and provide examples both in RDF and JSON formats. A better experience would be if there was just a toggle in the docs to show every example using JSON or show every example using RDF. This would be similar to how many Google APIs (here’s a random example) let you choose which programing language you want to view examples in (e.g. python, Javascript, Go, etc).
As another example, and this is opinion, but I’m really not liking the use of the term “predicate” in dgraph. This could be because my background is with Javascript and Ruby and when I typically see the use of “predicate” it’s referring to a boolean function, but in general I would find replacing the word “predicate” in the docs with the word “property” to be much more intuitive. I think a node is most intuitively thought of as an object or a document, both of which have properties. This would also better reflect the terminology used by other graph and nosql databases, as well as the terminology of the (theoretically upcoming) GQL standard. Dgraph seems to be an outlier here, but perhaps there is a popular precedent I’m not aware of (and obviously this is just one opinion).
Similarly, calling edge properties “facets” instead of the more obvious “edge property” or “edge attribute” doesn’t seem like the best choice. I realize that edge properties have subtle differences vs node properties, but in this case I don’t think that justifies giving them a different, less intuitive name. Any time you find yourself giving something a name and then explaining what that name means to the reader, you should pause and ask yourself, “Why don’t we just drop the proprietary name and ‘use the intuitive explanation’ instead?” Some times there are reasons to rename something, but I don’t think “facets” reaches that bar.
Anyway, obviously there’s a lot of opinion here and again, despite frustrations I do really appreciate all the work that has gone into dgraph.
Edit
As a random musing: it just occurred to me that I’ve never heard of a development team practicing documentation first development (and I’ve never done this myself). I wonder how a project would turn out if you tried writing the docs first, as you would like to be able to describe the API, and then tried making the app. This is basically what UI driven apps do, when a designer designs the UX first and then codes the app to mimic that UX.