A quick update on some recent activities.
The engineering team is steadily improving our code base and should announce our v23 soon. I’m personally looking forward to this major step as the merge of our cloud branch and community branch will be a starting point to implement new features. It will also purge a good list of issues.
But today I wanted to share the work we are doing on the documentation. We are revamping the documentation step by step to improve usability and help new Dgraph users as well as seasoned practitioners to leverage the power of Dgraph.
We are reviewing each page and organizing the content more clearly into concept, task, tutorial, or reference pages. We are also taking the opportunity to re-test the instructions and correct them when needed. We are also including some of the great work of the community.
For example you may want to check
An new explanation of the DQL syntax coming from a discuss post.
We are also doing some technical work to have the search working on the older versions. It was broken and we had to review the logic between Hugo, Netlify, Algolia crawler and indexes. Some fun scripting involved and some hiccups to expect as I’m testing the solution at the moment. So don’t worry if you see some messages about the current version in the doc. I’ll post when the search capability will be fully functional.
It’s a tedious work but very rewarding as it’s an opportunity for the team to go into some feature details. As I used to say, It’s surprising what you can learn by just reading the doc ! But the doc has to be readable.
It’s a continuous effort and we expect to have the whole doc revamped this quarter. We will also review all the tutorials.
Feel free to share you advice on the tutorials you found useful and the ones you would like to see !
We have deployed the doc of v22.0 and v21.03 ( the 2 versions officially supported) but we will put 21.12 back in the doc site too.
If you urgently need the v21.12 doc it is available here
BTW I have seen the suggestion to use Dgraph instead of Algolia. That’s a good idea for a project :
anyone interested in building a crawler, indexer and metadata management solution based on Dgraph ?
Hey @Raphael I’m confused, are you saying your cloud branch (that we can’t access) and community branch are gonna be merged ? or are you just saying that they both will get those new features in ?
@cscetbon yes, the Dgraph engine running in our Cloud and the engine available on community branch will be the same ! Starting at the next release, we want Dgraph new features and bug corrections to be available on Cloud and on community at the same time. It’s a big change !
The Cloud offering has a some management tooling and UIs (the Cloud console) that will stay private.
You might be interested in JSON mutation format where we put explanations requested and provided by the community about JSON, blank node, relationships etc…, It’s now in the doc, as requested.
We have also merged the Cloud doc so we can better reference common concepts in the doc.
We had recent requests about the @auth directive, and more broadly about how to secure Dgraph cluster and your GraphQL API. We are working at integrating the different explanations from Discuss posts, current documentation and tutorials to clearly explain Dgraph.Authorization schema annotation , GraphQL anonymous access (cloud feature), @auth directive.
Nice, I think these are much easier to follow! As a suggestion for the future, also having client specific versions would help a lot of people (e.g. Python, Go, JS etc). This is because the syntax for set, delete, upsert etc varies a little and currently users still have to translate that part.
Thanks for the feedabck @RJKeevil. For the clients, we would like to clarify GraphQL clients (make it clear that we don’t have a GraphQL client but we work well with any popular GraphQL client), programmatic clients (Go, Java, python…) and UI clients (Ratel and more to come).
For the programmatic clients, could you clarify your request for the versions : do you think we should align the client version with Dgraph version and have the clients built with the Dgraph build or are you referring to a separate doc page for clients so you can browse the client version history ?
Hi Raphael, I mean that in https://dgraph.io/docs/dql-syntax/dql-mutation/ page, in “set block” you have examples/tabs for json and RDF. I think it would be more useful to show how to do this in Python, Golang or Javascript, as now as a user I need to translate that json example into how the client actually expects a query to be provided. An example would be like the Qdrant docs, that give a python equivalent for each htttp call (Collections - Qdrant)
There is NO correlation between dql, graphql, rdf, json etc…
This is completely different than javascript, python, golang, c#…
The tabs for rdf vs json are a completely different concept. @Raphael - I find the changes here highly valuable, and you should not add python or any language on this page.
There should be a separate place for python programmers to understand the concepts.
Thanks for the comment @jdgamble555. We where debating how to organize the client documentation : either by tasks (use cases) and give the different flavors on each task, or by technology and describe all the tasks you can do with the python client, go client, … (as it is now) .
I guess when you are a python developer , you are not really interested in all the Go examples.
The organization of the client doc by language seems a better approach.
Let’s give a try at our client doc improvement and we will pay attention to the community feedback.
I think that Clerk.dev has some of the nicer docs I’ve read through recently.
They have the general concepts and clerk.dev specific information at the top level and then the majority of the information one layer down under SDK/ specific language / sdk integrations in their own sections / getting started flows.
On sign up they basically ask if you are implementing Clerk with any of these x frameworks. If you click one it takes you to the getting started for that specific framework.
We have started to include elements about GraphQL and DQL interoperability. We also included elements from @amaster507 paper (thank you) and explained the differences between GraphQL schema and Dgraph types and predicates. We also started to list some benefits (and risks) by covering GraphQL data ingestion and data cleaning using DQL. It’s a work in progress and a place to put community tips on those subjects. https://dgraph.io/docs/graphql-dql/
We have also moved the “clients” section in DQL to clarify that Dgraph clients are DQL only and created a section GraphQL Client - GraphQL to explain the /graphql endpoint and headers better and to clarify the usage of GraphQL tools (IDE and clients).
We are working now on consolidating the Dgraph Administration documentation.
You will also notice that we have moved tutorials close to the documentation pages and organized them by roles targeting application developers, data engineers, and administrators. It’s at Dgraph Tutorials - Learn
Please let me know if you have good resources or ideas to create some Dgraph administration tutorials…
These pages are looking good. Glad to see some of this cleared up directly in the docs. Interesting to see tuts being brought back beside the docs, it all sometimes to be a big circle.
