Documentation Next Gen

[iamdadmin]

Description

I'd like to suggest that an overall strategy is developed for Documentation Next Gen, to take the Tempest Docs to a place where more experienced Devs can get the critical information they need, and less experienced Devs get a bit more hand-holding through Tempest.

My iidea is that it would be good to have

• "API" documentation, an in-depth guide to every relevant class and every relevant method therein. This could be driven by the docblock in each file, and harvested dynamically, such that the presence of relevant and updated docblocks is mandatory on acceptance of a PR, and CI/CD extracts the changes when a PR is applied.
• The Tempest Handbook, an evolution on what we have today, structured in a logical flow out from the perspective of someone picking up Tempest and working through the first steps of initialising an application, running a dev server or docker, working with databases, adding auth etc etc. Many other frameworks have done this, so we needn't reinvent the wheel, but as it stands many of the pages are long and cover a lot of ground so could be broken up and flow better.
  • Under this, There’s definitely a beginner level of detail that can be pulled out showing one way of doing things, enough for your average person to get started. It need not be opinionated, just consistent throughout so people understand how to work with Tempest.
  • Then, a matching advanced topics version of the page showing other supported ways of doing things.
• Tutorials on "how to do a thing" or a “feature apotlight”? These perhaps could be picked up from anyone who wishes to PR one and maybe issued out as a blog article or something?
• A simple login & auth starter application with a small dashboard, both Vite, Inertia and Vue, and Tempest/View versions perhaps.

I’ll perhaps figure out a rough outline and see if any of what I’m saying is appealing.

[innocenzi]

I always love docs improvements! :)

The Tempest Handbook, an evolution on what we have today, structured in a logical flow out from the perspective of someone picking up Tempest and working through the first steps of initialising an application, running a dev server or docker, working with databases, adding auth etc etc.

That's something that I tried to do with the current hierarchy, actually! You have the "Getting started" that explains what Tempest is, what it brings to the table, and how to install it.

Then you have the "Essentials", features that every application need and concepts specific to Tempest, such as discovery. The idea is to only have, well, the essentials in there. Maybe console commands should not be there, but authentication should, for instance.

And then you have the "Features", named after specific topics that one might look for, such as sending emails, handling exceptions, or doing validation.

There could be some improvements for sure, but I believe that we don't need to transform this into something else, but simply iterate on it.

Tutorials on "how to do a thing" or a “feature apotlight”? These perhaps could be picked up from anyone who wishes to PR one and maybe issued out as a blog article or something?

That's definitely something I thought about. I wanted to call it "Recipes", and have a list of tutorials on how to do different stuff, eg. implementation authentication from scratch.

Would love to have something like that!

A simple login & auth starter application with a small dashboard, both Vite, Inertia and Vue, and Tempest/View versions perhaps.

That's something I'm less keen on—we already have so many more things to work on, that providing and maintaining starters for stacks the core team might not even use themselves is not something I'd recommend.