RFC: Adopt the four-quandrant documentation system

[bajtos]

I am proposing to adopt the documentation system described at https://documentation.divio.com and successfully used by Django and others, and reorganize our documentation along the following four directions:

1. Tutorials
2. How-to guides
3. Reference
4. Background/Key concepts/Discussion/Explanation

Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should all be integrated into your documentation.

You can also watch the talk from PyCon Australia 2017 where this system was explained: https://youtu.be/t4vKPhjcMZg

In this issue, I'd like to keep the discussion at high-level and reach consensus whether such documentation system is something we all agree to asses and if we decide to implement it, then we will be all following it going forward.

An example of an existing doc page that's mixing different directions:

• Key concepts >> Server is a mixture of
  • Some Background explanation of what is a Server.
  • How-to guides for customizing CORS, configuring REST API Explorer, etc.
  • Reference of rest options

Next steps

• Discuss the proposal and reach consensus on whether we want to pursue this direction or not. If yes:
• A spike story to identify the first few steps of what will become a longer journey. For example, how to re-arrange the sidebar and existing pages, where to keep reference guides (inside docs or as tsdoc comments in code?), etc.
• Many small stories to review each existing doc page and rework it to follow the new system - extract How-to guides, extract Reference material, rework Explanations, and so on.

[dhmlau]

@bajtos, I agree with you that some of our docs page are mixed with how-tos and explanation.
Are you thinking of each page (if applicable) to have 4 sections, or there will be 4 categories in the docs?

small stories to review each existing doc page and rework it to follow the new system

+1

[raymondfeng]

@bajtos In addition to what you proposed, I would like all of us to think about the following perspectives:

• Persona (Platform developer, API developer, Microservice developers, Integration Developer)
• Usage scenarios (Expose REST APIs, Expose GraphQL, Expose gRPC, access databases, access existing services, enable authentication/authorization, Cloud native observability, Use third-party ORMs, schedule jobs, use Pub/Sub, ...)
• Architectural layering (How are different packages positioned in the LB story, how to achieve 12 factors, how to extend/compose)