Merging GraphQL and Dgraph docs

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.

@vvbalaji

UPDATE

  • 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.

Let’s talk today about this.

1 Like

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:

  • Current docs only support 2 level of nesting but we need three level nesting. See https://graphql.dgraph.io/doc/schema/types for example.
  • 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.

2 Likes

Current state

What is the doc layout to achieve this?

@dmai: it will be in dgraph repo for now

@pawan I will have a meeting w/ our SEO agency today and will get a checklist for the merging.

@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
  • Ensure that any applicable navigation links are switched from graphqp.dgraph.io to dgraph.io/docs/graphql
  • Be sure to include the RankScience JS snippet on the new /docs/graphql subdirectory |

<script type="text/javascript" src="https://cdn.ranksci.com/dgraph-411505.min.js"></script>
2 Likes

Thanks @zhenni. How easy or difficult would it be for the SEO agency to verify that we did things the right way after the merge?

@vvbalaji they say they can check the merge the day after immediately and give us the feedback. So just let me know when the merge is done. :slight_smile:

Notes from meeting with @vardhanapoorv

  • Most of the docs have been ported atleast locally. Apoorv to fix broken internal links today and create a PR for the docs.
  • Apoorv to talk to @dmai about how to deploy this so that its available on docs.dgraph.io/docs/graphql and get it up by tomorrow.
  • We start working on getting redirects in place tomorrow.

Things to fix next week if we don’t find time this week:

  1. Syntax highlighting for GraphQL - Modify Hugo theme to enable this.
  2. Algolia search - GraphQL should have its own search and should not return results from Dgraph.
  3. Edit Page button - Make this a variable within the theme so that it points to the correct place to edit GraphQL docs.
  4. Tour link on top - Should be removed from GraphQL docs.

The docs for GraphQL would lie in a different folder from the current Dgraph docs to achieve this. This is what Apoorv is currently doing.

Yes please, let’s move docs into a separate repo, primarily for practical reasons.

  • Don’t want to get approvals from dgraph CODE_OWNERS for merging in Slash Docs
  • Don’t want to have to wait for CI, code checks for the docs

@pawan get some help from @gja’s team to integrate Discourse comments to each page in the documentation.

1 Like

This is awesome, each page will have it’s own FAQ section as well as answers!

1 Like

Sounds good to me. We can move it do a different Git repo or maybe we can just rework the current repo to have Hugo docs instead of Gatsby docs.

Ok, let me talk to @gja about this tomorrow.

An initial version of how these docs would look is live at https://frosty-feynman-6ed421.netlify.app/how-dgraph-graphql-works/. We’ll soon get it live at docs.dgraph.io/docs/graphql.

1 Like

@vardhanapoorv: where would https://graphql.dgraph.io/dgraph-graphql/quick-start exist in the new merged doc?

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/.

Thanks @vardhanapoorv. @pawan do we have a sync up scheduled with Marisa for the new docs home page?

Updates

  • 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.

1 Like

The PR is raised for release v20.07.

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.