Lighthouse: New layout for docs

[olivernybroe]

I often see questions on Slack about users asking how to do X and X, which are things that are mentions in our docs, however almost everything the user want's to do is mentioned in API References.

I think we need a structure to easily browse the functionality of the framework, in a more newcomer friendly way.
The API References are nice, but it is a reference, it is not something you go into when you wanna learn how to paginate.

An example structure could be something like this

• Getting Started
• The Basics ( This will cover something that is also covered in other topics, but just shorter and then referencing for details)
  
  
  
  • Schemas
  
  
  • Directives
  
  
• Types
  
  
  
  • Getting Started
  
  
  • Scalars
  
  
  • Enums
  
  
• Queries
  
  
  
  • Getting Started
  
  
  • Pagination
  
  
  • Resolvers
  
  
  • Relay
  
  
• Mutations
  
  
  
  • Getting Started
  
  
  • Resolvers
  
  
  • Relay
  
  
• Security
  
  
  
  • Getting Started
  
  
  • Authentication
  
  
  • Authorization
  
  
  • Validation
  
  
• Extensions
  
  
  
  • Getting Started
  
  
  • Monitoring
  
  
  • Deferred Fields
  
  
  • File Upload
  
  
  • Subscriptions
  
  
• Testing
  
  
  
  • Getting Started
  
  
  • GraphQL Playground
  
  
  • Integration Testing
  
  
  • Unit Testing
  
  
  • Mocking
  
  
• Package Development
  
  
  
  • Getting Started
  
  
  • Extending the schema
  
  
  • Extending the request
  
  
• API References

Didn't want to write it all out, but I think it shows what I mean.

[spawnia]

I like the structure you are suggesting, should make things easier to find.

We should keep the API reference though, it is essential to have it for looking up the name of arguments or similar things.

I am open to switching to this new structure for a 3.1 release. For the initial v3, we should keep the structure the same, to make the transition easier.

[olivernybroe]

We should keep the API reference though, it is essential to have it for looking up the name of arguments or similar things.

Totally agree. Just forgot to add it to my suggestions :)

[eriktisme]

Is it also possible to add an option to search the docs?

[olivernybroe]

@eriktisme that is more of a new feature for the docs. I totally agree with we should have that feature, but this discussion is more about what should actually be in the docs.

You are more than welcome to make a pull request which adds search in the current docs.

[eriktisme]

@olivernybroe Alright I'll try and create a pull request which adds search to the docs

[spawnia]

@olivernybroe we can continue on this, v3 docs are released.