Keystone: Improve documentation strategy

[timleslie]

In order to continually improve our documentation strategy, it will help to have a framework in which to think about things. This slide gives a nice example of the different types of documentation we will need to generate, and how they relate to each other.

Watch the full talk here.

Some short term items we can start working on are:

• [ ] Reference: Generate inline docs for the graphQL API which can be access through the graphiql interface (possibly linking out to more detailed resources)
  
  
  
  • [ ] How-to: Provide code snippets for how to do certain things, such as creating lists with relationships, etc.
  
  
  • [ ] FIXME: This list can and should be extended.
  
  

[jossmac]

The gatsby marketing website does this really well with a combination of markdown/snippets and documentation.js.

[molomby]

Re: docs -- there was talk of creating a set of demo/test data that could be easily seeded into the DB and could form the basis for examples, sandboxes, online demos, etc.

Does anyone else remember the Northwind database that came with MSSQL? It was fake but structured to utilise much of the platform's functionality and had enough data it could be used to demo different approches to building queries, etc. They used it through out the docs and, because everyone had a copy of the DB, you could just copy/paste the queries and start playing around.

A related example is the Star Wars data used throughout the GraphQL.org site. I'm not sure if you can actually download a copy but the data itself is so familiar it's perfect for communicating query functionality.

We should have something similar, no? (OMG; we could do a gelato company!? @bladey!)

[molomby]

See also #173, #226

[jesstelford]

A good example doc: https://atlaskit.atlassian.com/packages/core/navigation-next/docs/controlling-navigation-views

[MadeByMike]

We have a doc strategy document. I think we can close this issue?