Graphback: Documentation refactor

[craicoverflow]

There have been a number of major changes between between 0.12.x and 0.14.x.

The documentation and website requires major restructuring/refactoring to adapt to the significant changes in Graphback.

This is a chance to simplify and focus the documentation to make it the best experience possible for users. This should be easier to achieve, since we now have reduced file generation to client documents and schema (optionals).

To get an idea of what has changed between these releases check https://github.com/aerogear/graphback/blob/master/docs/releases.md#0140

Sitemap Progress

• [x] Getting Started
  
  
  
  • [x] Why use Graphback? #1636
  
  
  • [x] Creating a new application #1636
  
  
  • [x] Adding Graphback to your project #1636
  
  
• [x] Data Model
  
  
  
  • [x] Common #1651
  
  
  • [x] For Postgres #1651
  
  
  • [x] For MongoDB #1651
  
  
• [x] CRUD #1655
  
  
  
  • [x] Introduction #165
  
  
  • [x] Queries #1655
    
    
    
    
    
    • [x] findMany
    
    
    
    • [x] getOne #1663
    
    
    
  
  
  • [x] Mutations #1633
    
    
    
    
    
    • [x] createOne #1633
    
    
    
    • [x] updateOne #1633
    
    
    
    • [x] deleteOne #1633
    
    
    
  
  
  • [x] Subscriptions
    
    
    
    
    
    • [x] onCreate
    
    
    
    • [x] onUpdate
    
    
    
    • [x] onDelete
    
    
    
  
  
• [x] Databases.
  
  
  
  • [x] Introduction
  
  
  • [x] MongoDB
    
    
    
    
    
    • [x] Installation
    
    
    
    • [x] Connecting to the database via mongodb package
    
    
    
    • [x] Provider usage
    
    
    
    • [x] Mongo specific annotation references? Covered in the Data Model page.
    
    
    
  
  
  • [x] PostgreSQL
    
    
    
    
    
    • [x] Installation
    
    
    
    • [x] Connecting to the database via Knex. Show example of db pooling etc
    
    
    
    • [x] Provider Usage
    
    
    
    • [x] Postgres annotation references? Covered in the Data model page
    
    
    
    • [x] Migrations Covered in theGraphQL Migrations page, We'll add a link to this page
    
    
    
    • [x] Custom scalar mapping Covered in the GraphQL Migrations page
    
    
    
  
  
  • [x] SQLLite
    
    
    
    
    
    • [x] Installation
    
    
    
    • [x] Provider Usage
    
    
    
  
  
• [x] Subscriptions
  
  
  
  • [x] Live Updates
  
  
• [x] Authentication
  
  
  
  • [x] Introduction
  
  
  • [x] Keycloak
  
  
• [x] Data Synchronization https://github.com/aerogear/graphback/pull/1665
  
  
  
  • [x] Introduction
  
  
  • [x] Soft deletes
  
  
• [x] Plugins
  
  
  
  • [x] SchemaCRUDPlugin
  
  
  • [x] ClientCRUDPlugin?
  
  
  • [x] Adding your own plugin https://github.com/aerogear/graphback/pull/1706
  
  
• [x] API Reference. See https://github.com/aerogear/graphback/issues/1702
• [x] CLI Reference
  
  
  
  • [x] Create Graphback
  
  
  • [ ] Graphback CLI
  
  
• [x] Running an API without code
  
  
  
  • [x] GraphQL Serve
  
  
• [x] GraphQL Migrations https://github.com/aerogear/graphback/pull/1657
  
  
  
  • [x] Introduction
  
  
  • [x] API Reference
  
  
  • [x] Database Design
  
  
  • [x] Operation filtering example
  
  
  • [x] Migration Plugins
  
  

[wtrocki]

I think we need to get our docs refined from the ground.
Starting with talking about getting started experience to the concepts then to the dev ideas like plugins. Things should be schema centric - currently we are concepts centric

[machi1990]

• Also, we should update annotations after https://github.com/aerogear/graphback/pull/1536

[craicoverflow]

I've put some thought into possible starting point for the website layout.
Let's use it to discuss what to bring in/what not to bring in and changes that can be made.

Introduction

Why use Graphback?

Getting Started

Creating a new application

Adding Graphback to your project

Data Model

This section would contain all of the information to set up your data model except for things specific to the different data sources. For this we could link to the databases section or else split like this section into:

• Common
• For Postgres
• For MongoDB

Model

CRUD

ID

Not null field

Relationships

Custom indexes

..?

CRUD

The CRUD documentation should fully list the CRUD specification that is used and it should not just link to GraphQLCRUD, since there can (and will) be variations between the two.

Introduction

Queries

findMany

getOne

Mutations

createOne

updateOne

deleteOne

Subscriptions

...

Databases

MongoDB

Configuration

Mongo specific annotation references?

PostgreSQL

Configuration

Postgres annotation references?

Migrations

API Reference (or should this be in the root API Reference section)

Custom scalar mapping

Subscriptions

...

Authentication

...

Data Synchronization

...

Plugins

SchemaCRUDPlugin

ClientCRUDPlugin?

Adding your own plugin

API Reference

buildGraphbackAPI

createCRUDService

createKnexDbProvider

createMongoDbProvider

GraphbackDataProvider

GraphbackCRUDService

GraphbackPlugin

...

[wtrocki]

All looks amazing!
Questions:
1) Subscriptions are not included? Forgotten?
2) Where this goes? Moving to package info:
https://graphback.dev/docs/next/db/dbmigrations
3) Where plugins will land? Do we need dev section?
https://graphback.dev/docs/next/plugins/plugin-intro
4) graphqlserve mentioned as alternative/note?
Hey you can also use it without template etc using:
https://graphback.dev/docs/next/intro/graphqlserve

I would not kill CLI docs yet until we figure out how to marry graphback and offix together.
I will check that next week

[craicoverflow]

1) Subscriptions are not included? Forgotten?

Subscriptions are there under CRUD - I just did not add the individual subscriptions headers for this as as it is a overview of the site structure. They will be there.

2) Where this goes? Moving to package info:
https://graphback.dev/docs/next/db/dbmigrations

See Databases > Migrations

3) Where plugins will land? Do we need dev section?

See Plugins

4) graphqlserve mentioned as alternative/note?

Yes, I don't think it needs its own page as it is very minimal right now and can't be configured. Adding it to getting started could distract focus of users and add noise to the navigation menu.

I would not kill CLI docs yet until we figure out how to marry graphback and offix together.

Agreed, not killing it just left it from this as not sure where to put it. CLI reference I guess.

[wtrocki]

Subscriptions are there under CRUD - I just did not add the individual subscriptions headers for this as as it is a overview of the site structure. They will be there.

We need subscription setup and integration - for context see voyager docs or starter :D

[machi1990]

@craicoverflow I was looking at the site map and noticed we've datasync there, from my recollection the docs were added by this https://github.com/aerogear/graphback/pull/1422 thanks to @ssd71 as part of 0.14 milestone, maybe we could just keep them as is and iterate on it as planned here https://github.com/aerogear/graphback/pull/1422#issuecomment-646024839. WDYT?

[craicoverflow]

Absolutely, I plan to just move the relevant, up-to-date content back without touching it, but wanted to have a clean slate to begin with.

[machi1990]

Planning to start working on graphql serve documentation.

After a quick chat with @craicoverflow we thought that it is worth to be added on top-level having it's on sidebar and not under getting started.

Thoughts? @wtrocki

[wtrocki]

+100. Good idea!

[machi1990]

I'll look into database migrations.

[machi1990]

@craicoverflow I was looking at the site map and noticed we've datasync there, from my recollection the docs were added by this #1422 thanks to @ssd71 as part of 0.14 milestone, maybe we could just keep them as is and iterate on it as planned here #1422 (comment). WDYT?

I've created https://github.com/aerogear/graphback/pull/1665 to take care of this.

/cc @craicoverflow

[wtrocki]

@machi1990 Amazing point. Let's leave datasync untouched. DataSync will by alpha itself so no need to improve docs etc. and they are fairly new and accurate anyway - reviewed this now

[craicoverflow]

A couple of things we should not forget to add:

API reference for KnexDBDataProvider
API ref for MongoDBDataProvider
Usage guide for createCRUDService - something I overlooked when doing the CRUD docs.

[wtrocki]

@machi1990 @craicoverflow Amazing work.

As for API reference. Would this be covered by typedoc?

[machi1990]

@machi1990 @craicoverflow Amazing work.

As for API reference. Would this be covered by typedoc?

Yes, I highly recommend we go that way. We have this issue https://github.com/aerogear/graphback/issues/1702 to cover it.

[machi1990]

The API Reference (which is the only outstanding item) docs we'll be done as part of https://github.com/aerogear/graphback/issues/1702: let's move the discussion there and close this issue.

Thanks @craicoverflow @wtrocki for the amazing work.