Docs rethink

[mcollina]

I think we might want to start thinking on how we can improve our docs.
fastify/website#145 is an example of a better Table of Contents and a change of structure in the Fastify docs. I would like to generalize that a bit.

In our docs, we mix the concept of a guide vs the concept of an API reference. In most cases, we teach how to use the framework but it's not clear where we document all the APIs. Viceversa, some of the guides are interleaved with API reference and it confuses folks on how to do things with Fastify.

As an example, we have https://www.fastify.io/docs/latest/Plugins/ and https://www.fastify.io/docs/latest/Write-Plugin/, https://www.fastify.io/docs/latest/Plugins-Guide/ and https://www.fastify.io/ecosystem/. Moreover, some of the plugins provide critical functionality such as fastify-static or fastify-cookie (and many others). We have a discoverability problem.

I propose to structure things as follows:

• Guides
  • Getting started
  • Structure your project
  • Request lifecycle
  • async/await and callbacks
  • How encapsulation work (decorators)
  • Parsing Content Types
  • Serverless
  • Typescript
  • LTS
  • Testing

• ....

• API Reference
  • Server
  • Request
  • Reply
  • ... everything else I have forgot

What do you think?

cc @fastify/core @davidmarkclements @Sambaboy

[Eomm]

I would add in Guides:

• Plugin
  • "For sure you are interested in.."
    • Authentication
    • CORS
    • Throws errors (fastify-sensible)

[jsumners]

Totally agree. Our docs are quite a mess.

[Sambaboy]

Yes, Matteo, agree with you it’s too scattered and consolidation in one place would be good. Agree with Manuel’s addition of Plugin chapter. From the start tell what is meant by “plugin” in Fastify. Before the “Getting Started” have a “Why Fastify?” section. Pitch why’s it better than the competition. There’s also got to be a place providing examples of when and when not to use Fastify. (Maybe in an appendix.) Perhaps place a link to the Matteo talk about it’s speed. (By the way that talk is now infamous.) Anyway, the most important thing is that Matteo went above 10k on Twitter. Bravo Matteo!!! Ciao!, Jon Rakestraw

…

On Feb 1, 2020, at 10:35 AM, James Sumners ***@***.***> wrote: Totally agree. Our docs are quite a mess. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2071?email_source=notifications&email_token=AOGSDERHHXSCIHFJ3GUWSCLRAWJEBA5CNFSM4KOSOJV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEKQ7XFQ#issuecomment-581041046>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOGSDESSDWMCHD6X4VVSJE3RAWJEBANCNFSM4KOSOJVQ>.

[Ethan-Arrowood]

I have a fair amount of guides / examples in the new TypeScript docs. I’m very happy with them and would love to see them in their own section of the docs.

While we are discussing a documentation redesign, what about a ‘typescript’ toggle similar to the ‘async’ toggle? This would really help boost Fastify as the leading TypeScript web server framework

[mcollina]

While we are discussing a documentation redesign, what about a ‘typescript’ toggle similar to the ‘async’ toggle? This would really help boost Fastify as the leading TypeScript web server framework

I would love this. However most of the docs are part of the .md file in this repo, and the toggle is managed on the website. I'd like to retain a style of the md files that is github-friendly. Could we automate that?

[Ethan-Arrowood]

I'm also thinking about it now, and most typescript versions of the examples are not different from the javascript version. so maybe a typescript toggle isn't the right thing to use here.

What might be better is to include links from certain parts to the TypeScript details docs of that part (i.e. Routing).

I'm going to split up my current TypeScript pr so that the examples are in their own files. This should help a lot in making the page more readable

[vrushti-mody]

How about splitting it into four sections as mentioned in this documentation guide? https://documentation.divio.com/

[mcollina]

I agree with said structure.
I think a good inspiration should be https://www.gatsbyjs.org.

[Sambaboy]

Speaking as a tech writer, the quad section structure vrushti-mody is a good conceptual prompt. Agree w/ mcollina that the Gatsby is a good framework. "Quick Start" is good way to start off after an Intro. Splitting Libraries into labels: Starter and Plugin (maybe for Fastify call it "Options" since 'plugin' has a special meaning in Fastify jargon. Gatsby has a Cheat Sheet section with a PDF download. That is Brilliant!!! Ciao!

[Eomm]

@luisorbaiceta Do you think we can close here?

[jsumners]

I think we have only just gotten started with this. The addition of guides support and the reorganization of docs laid the groundwork for being able to add the guides suggested in the original post.

[luisorbaiceta]

Agree with @jsumners. Now that we can nest content, comes the interesting part of the issue, the content itself. It terms of the website, the next thing would be: fastify/website#273

[Eomm]

Superseded by: https://github.com/orgs/fastify/projects/7

Closing

cc @metcoder95 there are ideas here!