[Umbrella issue] Restructuring the documentation

[divya-mohan0209]

This is a suggestion for restructuring the documentation based on the Divio paradigm

The TOC ends up looking as below

• Introduction
• Quickstart a.k.a. creating your very first component (This is the Tutorial section fleshed out a bit more with pre-requisites from the Language Support Section and also renamed)
• Understanding the Component Model (Explanation)
  • Why the component model?
  • Components
  • Interfaces
  • WIT
  • Worlds
  • Packages
  • Canonical ABI
• Using the Component Model (How to)
  • Creating and consuming components
  • Authoring components
  • Composing components
  • Running components
  • Distributing components
• Reference documentation (Reference implementations of the Component Model)
  • Language support for components
  • Rust
  • Javascript
  • Python

[itowlson]

This looks good to me. One perhaps personal preference: I would be inclined to put the "why" ahead of the quick start unless the introduction contains enough "why" material to give the reader context for what follows (and impetus to move on). But that's a nit in the overall structure. Thanks!

Another vague thought based on some of the organisational struggles with the first draft: would it make sense to move "language support" into the how-to section? Or is it better being more visible at the top level?

[kate-goldenring]

I've never heard of the Divio paradigm -- that's a really nice framework. My main concern is the quickstart/tutorial, since it could be redundant to the language guides, but definitely worth the effort to give people a quick happy path

[divya-mohan0209]

@itowlson

This looks good to me. One perhaps personal preference: I would be inclined to put the "why" ahead of the quick start unless the introduction contains enough "why" material to give the reader context for what follows (and impetus to move on). But that's a nit in the overall structure. Thanks!

I did think of this too and was wondering if we could move it to the introduction as a sub-section instead of the explanation. WDYT?

Another vague thought based on some of the organisational struggles with the first draft: would it make sense to move "language support" into the how-to section? Or is it better being more visible at the top level?

So, the thing with languages is that splitting makes more sense IMO. One of the supported languages is required as a prerequisite to work with the component model. So, putting that up there makes sense to me. Similarly, getting the building a component in the how-to section also makes more sense than putting it in the Quickstart. Thoughts?

@kate-goldenring :

I've never heard of the Divio paradigm -- that's a really nice framework. My main concern is the quickstart/tutorial, since it could be redundant to the language guides, but definitely worth the effort to give people a quick happy path

IMO, the language guides need to be split up because you need one of the supported languages as a prerequisite to work with the component model. The installation subsection can go into the pre-requisites while the building bits can go into the how-to section. WDYT?

[itowlson]

Moving the "why" material (or a summary of it?) to the introduction sounds like a good plan.

I'm not quite sure what you envisage with splitting up the language guides. Are you thinking that instead of a (say) Rust guide with sections on exporting and importing and building etc. in Rust, and a JS guide with sections on doing the same in JS, we would have a "how to export" guide and a "how to import" guide and so on, and those guides would have sub-sections on "how to export in Rust" / "how to export in JS" / etc.? Or are you referring to the splitting out of language guides from the how-to section as shown in your original post?

[kate-goldenring]

IMO, the language guides need to be split up because you need one of the supported languages as a prerequisite to work with the component model. The installation subsection can go into the pre-requisites while the building bits can go into the how-to section. WDYT?

I am not sure i am quite clear on how the tutorial has language specific pre-requisites and then achieves consistency, since the tooling for building components is rarely language agnostic. But we could have a subset of languages for the tutorial (say Rust and JS) while more fleshed out in the language guide (Go, Python, C, etc).

[yordis]

This is a suggestion for restructuring the documentation based on the Divio paradigm

Side note, it is called https://diataxis.fr/ nowadays. TL;DR: the author used to work for Divio.

It matters because it will help you to search and find more active community it is around Diataxis. There is a Slack Channel with active people helping each other. You can find the Slack server here: https://www.writethedocs.org/slack/ The original author of Diataxis/Divio is there helping people.

I would lean on that community to gather feedback.

One recommendation I have is to call out the Doc structure. I will help from contributors to have a set of guidelines, and also readers to understand the intent behind the docs.

[divya-mohan0209]

@itowlson and @kate-goldenring I was unclear, I am sorry. I'll try explaining it better below.

Context:

In the docs, currently, we have the language guides consisting of two sections (broadly speaking):

• one that deals with the installation of the tool (jco, componentize-py, cargo-component) that's need to author the component, and
• the other that deals with actually authoring the component & running it.

My suggestion

• To retain the section that deals with the authoring & running of components within the language-specific guides and,
• To move the installation of the language-specific tooling and put it in the prerequisites section.

Why?

With this, the readers will have an idea what needs to be installed before they reach the section of authoring a component and/or language guides.

[divya-mohan0209]

As I was typing out the above, it also struck me that since the tutorial requires knowledge from other sections, it would not be a quickstart per se. In the sense, it doesn't give the people a hands-on overview of the component model within a couple of minutes.

What I'd recommend as a quickstart would be the language-agnostic one authored with wasm-tools and run with wasmtime. We would need to flesh it out a bit better, of course.

We could then refer to the tutorial that we have currently as an advanced tutorial, so that it wraps up our documentation by recapping whatever has been learned previously.

The revised TOC would look something like the below:

• Introduction
• Getting Started
  • Prerequisites (tools that are needed by the user to create a component)
  • Quickstart (language-agnostic example with wasmtime)
• Understanding the Component Model (Explanation)
  • Why the component model?
  • Components
  • Interfaces
  • WIT
  • Worlds
  • Packages
  • Canonical ABI
• Using the Component Model (How to)
  • Creating and consuming components
  • Authoring components
  • Composing components
  • Running components
  • Distributing components
• Reference documentation (Reference implementations of the Component Model)
  • Runtime Support
    • wasmtime
    • jco
• Language support for components
  • Rust
  • Javascript
  • Python
• Advanced Tutorial (The tutorial that we have currently within the docs)

[kate-goldenring]

@divya-mohan0209 i like this outline. I'd be interested in more feedback on whether WAT being the first tutorial/introduction into Components is unideal, but as you say, i think language agnostic is likely our best bet. The prerequisites section may be sparse given that it is language dependent but there are clear prerequisites to the quickstart.

[itowlson]

@kate-goldenring I would really not want the first tutorial/introduction to use WAT. That is not going to speak to anyone in the target audience, and for many developers is going to be deeply offputting.

[kate-goldenring]

@itowlson i had an inkling of feeling similar. Back to the drawing board of how to set up an "easy" quickstart.

[ThorstenHans]

@divya-mohan0209 the Divio paradigm looks really nice. I also like the most recent outline draft.

I also agree with @itowlson and @kate-goldenring to go with anything but WAT for the first sample. I was thinking about using pseudo code to move from theory towards practice... but that may be a bit too dry for the reader. Usually, people wanna get something up and running quickly, to spark their ideas.

What about building the most simple sample in multiple languages to address different audiences?

Although this might be a bit more effort, I see the following advantages:

1. It makes the component model more accessible for a broader audience (they see as early as possible how to do xyz using their language of choice)
2. Readers can quickly get an understanding or at least an idea of how guest/host implementations may look like in different languages
3. Having the basics sorted out for every language supported, each language guide can pick up from the same point

Ultimately, I would suggest modifying the structure to this:

• Introduction
• Getting Started
  • Prerequisites (tools that are needed by the user to create a component)
  • Quickstart (describing what will be build in the quickstart and allow readers to jump to any of the children)
    • Rust Quickstart
    • JavaScript Quickstart
    • Python Quickstart
• ....

[kate-goldenring]

I like the idea of having a quickstart for each language. Another option is that the quickstart could be less of a quickstart to building components and more a quickstart to composing and using components. We could provide two already built components and walk through inspecting their interfaces with wasm-tools component wit, composing, and then running with wasmtime.

[divya-mohan0209]

@kate-goldenring: Quickstart to composing & using components sounds like a really good proposal. It'd give the person reading our documentation a good feel about the value prop right at the outset. Of course, that'd mean fixing the prerequisites section as well.

[itowlson]

I'm dubious about this as a sole quick start until there is a sufficient repertoire of off-the-shelf components to make "I will build a thing by composing things from the registry" a reasonable way to get started. But alongside @ThorstenHans' per-language starter guides it would be good. Although I'm not sure how "quick" a start it becomes at that point...! grin

[divya-mohan0209]

@itowlson : Not trying to push the agenda here, but we can definitely make it something like the Quickstart dropdown we have on Rancher docs for deploying Rancher on various platforms. WDYT?

[itowlson]

We can, but with a quick start per language, it starts to look like the quick starts are part of the language docs - otherwise the (e.g.) Befunge docs get split across the Befunge quick start in the QS section and the Befunge detail in the language section. And then the global "quick start" becomes a page of links to the various language QS pages.

Pulling the perspective out a bit, you originally created this issue as a proposal for the structure of the book as a whole, and I feel we have rather beached on the tricky detail of the quick start. What if we decoupled the quick start from the other changes so we could progress the larger work without waiting on the QS problem?

[divya-mohan0209]

That works for me if it's okay with everyone else. Would our next steps be to split this into smaller chunks of work with the help of issues and invite contributions? I can take on some of the rewriting.

[itowlson]

Sounds good - thanks!