Rework index #275

rsill-neo4j · 2025-07-17T10:05:28Z

All up for discussion :)

Liam-Doodson

This looks like a massive improvement 👏 Just a couple of small comments

Liam-Doodson · 2025-07-18T10:07:36Z

modules/ROOT/pages/using-the-library.adoc

+- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop.
+
+
+== Under the hood


Not sure of other people's opinion but this section probably belongs more with "how it works" than "using the library"

the N+1 problem and the fact that the library uses cypher behind the scenes are both things i recall were criticized as irrelevant for the index page :)
i agree though, it's definitely "how it works" - maybe we need another page that elaborates on this, while the section on the index page is really just about the simple example?

I think they were more called out because it's not the main thing that's interesting about how the library works (and we needed the new stuff you've added 😄).

I think if we were to add them back to the bottom of the "how it works" section though it would make the most sense to me. Happy to hear what others think about that though

Liam-Doodson · 2025-07-18T10:12:06Z

modules/ROOT/pages/using-the-library.adoc

+= Using the library
+:description: Learn how to use the Neo4j GraphQL Library with your technology stack.
+
+== Library features


I'm also not 100% sure this belongs here long term. That being said it see some value in it for now as it's actually quite hard to get a sense of the library features and how it's configured with the current docs layout as most of it buried

Not sure if anyone has any better ideas for this but maybe we leave for now and take another look once we've gone further with this rework of the docs?

moved the section

modules/ROOT/pages/versioning.adoc

angrykoala · 2025-07-21T16:27:49Z

modules/ROOT/pages/versioning.adoc

@@ -0,0 +1,17 @@
+= Versioning
+:description: The approach to versioning of the Neo4j GraphQL Library.


Is it worth mentioning the LTS vs latest approach?

Currently version 5 is LTS, which is still maintained but no new features are added, whilst version 7 (recommended) is actively being worked on

angrykoala · 2025-07-21T16:29:02Z

modules/ROOT/pages/using-the-library.adoc

@@ -0,0 +1,40 @@
+= Using the library


Could this be a bit confusing title?

I expected this to describe how to use the library, not how to integrate with my stack

angrykoala · 2025-07-21T16:31:49Z

modules/ROOT/pages/using-the-library.adoc

+The Neo4j GraphQL Library features:
+
+- Automatic generation of xref::queries-aggregations/queries.adoc[Queries] and xref::mutations/index.adoc[Mutations] for CRUD interactions.
+- xref::/types/index.adoc[Types], including temporal and spatial.
+- Support for both node and relationship properties.
+- Extensibility through the xref::/directives/custom-logic.adoc#_cypher[`@cypher` directive] and/or xref::/directives/custom-logic.adoc#_customresolver[Custom Resolvers].
+- Extensive xref::filtering.adoc[Filtering], xref::queries-aggregations/sorting.adoc[Sorting] and xref::/queries-aggregations/pagination.adoc[Pagination] options.
+- Options for xref::/directives/database-mapping.adoc[Database mapping] and value xref::/directives/autogeneration.adoc[Autogeneration].
+- xref::/security/index.adoc[Security options] and additional xref::schema-configuration/index.adoc[Schema Configuration].
+- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop.


I'm not sure if this is helpful here

This feels more like a "features" blurb to show off in the index, but we may want to refine a bit the list of features

There are some pretty big ones missing such as subscription and federation integration. And potentially Database mapping and autogeneration do not feel as big as to be part of the "main features" list?

angrykoala · 2025-07-21T16:37:35Z

modules/ROOT/pages/index.adoc

+* highly flexible and low-code
+* open source
+* a JavaScript library
+* leveraging graph-native data


I'm not 100% sure why this was moved to be a list, it feels much more concise to keep it as a single sentence, and maybe use the space for a reduced list of features to showcase at the beginning?

Maybe we can discuss on an introduction for the GraphQL library?

Something on the lines of:

Neo4j GraphQL is a low code tool to create powerful GraphQL APIs for your Neo4j database.

And then move on to a bullet list of the main features maybe?

* Out of the box API * On prem and managed service on Aura * Customizable API * Authorization and Authentication * Custom Cypher * Subscriptions * GraphQL Federation support

angrykoala · 2025-07-21T16:38:48Z

modules/ROOT/pages/index.adoc

+[source, graphql, indent=0]
+----
+mutation {
+  createProducts(
+    input: [
+      {
+        productName: "New Product"
+        category: { create: [{ node: { categoryName: "New Category" } }] }
+      }
+    ]
+  ) {
+    products {
+      productName
+      category {
+        categoryName
+      }
+    }
+  }
+}
+----
+
+Here is an example of how you can query existing data:
+
+[source, graphql, indent=0]
+----
+query {
+  products {
+    productName
+    category {
+      categoryName
+    }
+  }
+}
+----


I would consider putting the query first, along with an example response, as this feels like the most prominent and use case

Co-authored-by: angrykoala <[email protected]>

Liam-Doodson · 2025-07-24T13:11:10Z

modules/ROOT/pages/index.adoc

-It can generate an entire executable schema with all of the additional types needed to execute queries and mutations to interact with your Neo4j database.
+Here is an example of how you can query existing data:
+
+[source, graphql, indent=0]


I think we need to give a small introduction to how the library works before going straight into a query. Otherwise this is essentially just describing GraphQL itself.

I liked the version you had here in the previous commit

Also I'm assuming this change was in response to the comment from @angrykoala but I think that was just about swapping the query & mutation order (which I probably also agree with)

well, with the small example there is no data yet without the mutation. i'll restore the section, and keep the order for now (since it makes the most sense to me). but i'll let myself be convinced otherwise :)

neo4j-docops-agent · 2025-07-24T16:13:02Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-graphql-275.surge.sh

New pages:

Updated pages:

created new pages, slimmed down the introduction

9652411

rsill-neo4j requested review from angrykoala, mjfwebb and Liam-Doodson July 17, 2025 10:05

Liam-Doodson reviewed Jul 18, 2025

View reviewed changes

moved a section

4f97601

Liam-Doodson approved these changes Jul 21, 2025

View reviewed changes

angrykoala reviewed Jul 21, 2025

View reviewed changes

rsill-neo4j and others added 3 commits July 23, 2025 10:30

Update modules/ROOT/pages/versioning.adoc

5c42503

Co-authored-by: angrykoala <[email protected]>

review suggestions

8010594

path change

4fbe814

Liam-Doodson reviewed Jul 24, 2025

View reviewed changes

restored intro, restored order for 'how it works' section

208f605

		- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop.


		== Under the hood

		@@ -0,0 +1,17 @@
		= Versioning
		:description: The approach to versioning of the Neo4j GraphQL Library.

Rework index #275

Are you sure you want to change the base?

Rework index #275

Uh oh!

Conversation

rsill-neo4j commented Jul 17, 2025

Uh oh!

Liam-Doodson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neo4j-docops-agent commented Jul 24, 2025

Uh oh!

Uh oh!