We aim to merge docs.dgraph.io and graphql.dgraph.io into a single site with a single repo. Since Dgraph docs use Hugo and GraphQL docs use GatsbyJS, we have some decisions to make here. The easiest approach seems to be to move the GraphQL docs to Hugo and merge them with Dgraph docs.
Pros
This would be easier to do as we just have to port over the GraphQL docs to the Dgraph repo along with other docs.
Hugo theme already has things like runnable, Algolia search etc.
Cons
We lose the cool design that we have in GraphQL docs for now until it is reworked upon later.
We canât use GatsbyJS which apparently seems to be more customizable than Hugo as per @vardhanapoorv.
The other options are to move the Dgraph docs to the GraphQL docs. That seems like more work initially where we first need to have additional things like runnable, search etc over first and then we can migrate the docs. A bigger question here is that is GatsbyJS significantly better than the Hugo theme for us to go in this direction? CC: @michaelcompton@vardhanapoorv who would know more about this.
Based on the conversation with @gja the aim right now is just to have a landing page for docs which links to Dgraph, GraphQL, Slash, Client etc docs and to get all of these docs under the same domain. That should be easier to do. Eventually, weâll use the same framework for all the docs but that is a long term solution. Weâll just have to be careful to make sure that the old links still work.
Just to clarify, I never commented on the two systems being kept separate (seeing some conversations between you and Tejas). In fact, Iâm just learning that GraphQL docs are written via Gatsby. If I had known earlier, I would not have approved another system, or at least questioned that decision very hard.
Had a chat with @vardhanapoorv about this. This is what we have decided.
The GraphQL docs would be available at https://dgraph.io/docs/graphql/ similar to how the badger docs are at Badgerdb documentation â. The other alternative would have been to have GraphQL as section along with other sections in the left side menu along with Mutations, Query Language etc. at https://dgraph.io/docs/. We have chosen the first approach because of the following reasons:
GraphQL docs and its different sections should stand out. It should not just be another section along with Mutations, Query language and GraphQL± as that would confuse the users.
Since GraphQL is only available from 20.03, we donât need to have a version selector for all the older versions for it.
Tasks to do
Migrate Documentation reference, Todo tutorial and Slash docs to a Hugo based theme.
Figure out which directory to keep the docs in, they can lie in a new folder inside the Dgraph repo for now and can be moved to a different repo if required later.
Redirects should work properly. Coordinate with @zhenni about that before making them live.
Have support for versions 20.03.0, 20.07.0 and master.
Deploy and make them go live
@vardhanapoorv is also going to share some screenshots of some initial pages by end of day today once he is done porting them.
@pawan@vvbalaji here is the note from the SEO agency on merging the GraphQL docs to under Dgraph.
Please ensure that 301 redirects are implemented (donât use javascript redirects or meta refresh)
Donât create redirect chains (where one redirect leads to another redirect, which leads to another redirect, ect). If possible, please link to the final destination URL
I am assuming you would be dropping âTutorialsâ, âExample Appsâ and âTools and Deploymentsâ sections from https://graphql.dgraph.io/dgraph-graphql/ as they donât have any content.
@vvbalaji I ported the quick-start content today. The todo tutorial was already ported. The remaining sections like âexample appsâ can be added whenever we have content ready for those.
I have added the GraphQL, Slash section to the Dgraph docs and created DQL section for GraphQL±, according to the discussion with @pawan today.
Updated - https://frosty-feynman-6ed421.netlify.app/.
https://dgraph.io/docs/master/ have been updated to have docs for GraphQL and Slash GraphQL. DQL is its own section now. This didnât break any existing links for DQL pages.
Things to do
The sidebar menu should be better so that when we click on a level 1 folder, it should not automatically expand level 2 folders.
Search has to be fixed to index the new pages.
Deploy to release 20.07.0 as well.
Redirection links have to be managed.
Tour should be removed from the top menu as it is a tour of DQL only.
@vvbalaji@mrjn please have a look to give any final feedback after which weâll redirect graphql.dgraph.io links to the docs.
Need to add redirection from graphql.dgraph.io. List is prepared. cc @dmai
Check why the search results on master are not updated.
Regarding version v20.03 should a PR be raised for every v20.03.1, v20.03.2 etc or just the main one.
