Skip to content

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

Open
wants to merge 6 commits into
base: 7.x
Choose a base branch
from
Open

Rework index #275

wants to merge 6 commits into from

Conversation

rsill-neo4j
Copy link
Contributor

All up for discussion :)

Copy link
Contributor

@Liam-Doodson Liam-Doodson left a 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
Copy link
Contributor

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"

Copy link
Contributor Author

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?

Copy link
Contributor

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
Copy link
Contributor

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?

Copy link
Contributor Author

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.
Copy link
Member

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
Copy link
Member

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

Comment on lines 6 to 15
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.
Copy link
Member

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?

Comment on lines 8 to 11
* highly flexible and low-code
* open source
* a JavaScript library
* leveraging graph-native data
Copy link
Member

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?

Copy link
Member

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

Comment on lines +40 to +73
[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
}
}
}
----
Copy link
Member

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

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]
Copy link
Contributor

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

Copy link
Contributor

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)

Copy link
Contributor Author

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 :)

@neo4j-docops-agent
Copy link
Collaborator

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

New pages:

Updated pages:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants