-
Notifications
You must be signed in to change notification settings - Fork 13
Rework index #275
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: 7.x
Are you sure you want to change the base?
Rework index #275
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks like a massive improvement 👏 Just a couple of small comments
- A xref::getting-started/toolbox.adoc[Toolbox] (UI) to experiment with your Neo4j GraphQL API on Neo4j Desktop. | ||
|
||
|
||
== Under the hood |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure of other people's opinion but this section probably belongs more with "how it works" than "using the library"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
= Using the library | ||
:description: Learn how to use the Neo4j GraphQL Library with your technology stack. | ||
|
||
== Library features |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
moved the section
@@ -0,0 +1,17 @@ | |||
= Versioning | |||
:description: The approach to versioning of the Neo4j GraphQL Library. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
@@ -0,0 +1,40 @@ | |||
= Using the library |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could this be a bit confusing title?
I expected this to describe how to use the library, not how to integrate with my stack
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
modules/ROOT/pages/index.adoc
Outdated
* highly flexible and low-code | ||
* open source | ||
* a JavaScript library | ||
* leveraging graph-native data |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
[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 | ||
} | ||
} | ||
} | ||
---- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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]>
modules/ROOT/pages/index.adoc
Outdated
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] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 :)
This PR includes documentation updates New pages: Updated pages: |
All up for discussion :)