V8-archive: How to structure documentation ?

[jooola]

Some project such as python project, and specially Django had some rough time with their documentation in the beginning. Such large project learned from there mistakes and some created guides on how to build a proper documentation.

Here is the video used a background for this ticket : https://www.youtube.com/watch?v=t4vKPhjcMZg

The main idea is to structure the documentation as described in the the talk (the 4 distinct parts). To do so, the repository might need some big path reconstructions.

First I would like to the people invested in the documentation repo watch the video, and then we can discuss whether this is the path we want to take.

[rijkvanzanten]

What is inherently wrong with the current structure?

Would you mind sharing the summary of that video (eg what those 4 parts are and how you intend to use them in the context of Directus)

[jooola]

@rijkvanzanten I might write a summary but that's a lot of work, maybe I'll do it in the next days. The video does bring a lot a details, it should be watched.

[rijkvanzanten]

You already seen it right? Just give me the most important points 😁

I don't see anything wrong with the current structure of the docs, nor do I have the time to invest in the research right now, so I'm probably not going to watch that video anytime soon....

[jooola]

Here is the author paper about his talk: https://www.divio.com/blog/documentation/ (broken link: see http://web.archive.org/web/20200312220117/https://www.divio.com/blog/documentation/ )

Here are the 4 mains parts:

What I see in our documentation is that the 4 parts a not properly separated, they are mixed together.

[benhaynes]

I agree that these are the four distinct parts of our Docs, let me cover each of these individually:

Tutorials

I wonder if this belongs in the Docs. We could push these out to something like Medium so they are easier to work with. Most of our "Guides" in the docs now are probably more of Tutorials. So we'd need to think through how we split this up (and when, since the core team won't have time for at least two months).

How-To Guides

We currently have a top-level guides section that holds all of these. There are two main Guides (User and Admin) and then many individual guides on different Admin/Developer features/concepts. I would be down to separate this out into a top-level User Guide, and a top-level Admin Guide though.

Explanation

This seems the same as Tutorials, but more conceptual? This might be what is getting moved into the codebase as readme.md files (right @rijkvanzanten ?). We would need to better understand what this content needs to be... otherwise I see it as being very similar to Tutorials.

Reference

We have this with the API Reference, and it's comprehensive... not sure if there is an equivalent on the user side.

Down to discuss this and more... but we need a clear plan of action and know who will execute these changes before getting started. Thanks @jooola !

[jooola]

I am gonna cherry pick a lot from the paper I mentioned above:

Let me explain some key details regarding my proposal, and I'll highlight some parts that are really bothering me in the current documentation.

Still I highly recommend to read the paper I liked above, please read it, it's not that long.

Some background/context

Tutorials

A tutorial:

• is learning-oriented
• allows the newcomer to get started
• is a lesson

Analogy: teaching a small child how to cook.

eg. Installing Directus with Nginx and Mariadb

I wonder if this belongs in the Docs. We could push these out to something like Medium so they are easier to work with.

Tutorials are a part of documentation, it should be. The problem with posts on medium is that they are fixed in time. A medium post will not get updated as often as the documentation, which could keep the tutorial up to date.

I would rather see people contribute to enhance a tutorial, rather than commenting on a blog post.

And I would not recommend maintaining tutorials on another platform.

Most of our "Guides" in the docs now are probably more of Tutorials. So we'd need to think through how we split this up (and when, since the core team won't have time for at least two months).

It is easy to mix both how-to guides and tutorials, but it is essential not to. See below to see the differences.

How-To Guides

A how-to guide:

• is goal-oriented
• shows how to solve a specific problem
• is a series of steps

Analogy: a recipe in a cookery book

eg. How to setup SSO with Oauth2 or How to create a new collection

We currently have a top-level guides section that holds all of these. There are two main Guides (User and Admin) and then many individual guides on different Admin/Developer features/concepts. I would be down to separate this out into a top-level User Guide, and a top-level Admin Guide though.

Splitting User / Admin guides is totally doable. As long as both does mention that they are how-to guides.

Explanation

An explanation:

• is understanding-oriented
• explains
• provides background and context

Analogy: an article on culinary social history

This seems the same as Tutorials, but more conceptual? This might be what is getting moved into the codebase as readme.md files (right @rijkvanzanten ?). We would need to better understand what this content needs to be... otherwise I see it as being very similar to Tutorials.

This would cover low level mechanism, maybe also github ticket that explain some decisions, it helps understand how the software works in details.

I would see a detailed schema of how the publish mechanism works. Since users do not need details when using tutorials, we don't want to bother them with details regarding how publishing works, those details should go in the explanation parts.

Same goes for "Choosing an architecture, this is a detailed explanation on what directus capabilities are, we don't want to bother newcomers with that much details.

Reference

A reference guide:

• is information-oriented
• describes the machinery
• is accurate and complete

Analogy: a reference encyclopaedia article

eg. REST API reference or SDK generated docs

We have this with the API Reference, and it's comprehensive... not sure if there is an equivalent on the user side.

The API reference is good IMO, but I would split this section in:

• Rest API ref
• SDK ref
• config ref
• other refs

Problems

Documentation is too flat

The documentation should have a deeper architecture, we see too much information at once, it should be split into little chunks with proper section names.

For instance the Guides sections present many many topics which could be split into sections.

Naming is... Damn...

Many titles are really not descriptive enough:

The title of a how-to document should tell the user exactly what it does. How to create a class-based view is a good title. Creating a class-based view or worse, Class-based views, are not.

Separate the main documentation from satellites

The current documentation mixes satellites projects with the main core project. For instance the SDK-js doc is lost within the Directus software guides.

This should be moved somewhere else.

I might have forgot some other concerns, but that's enough for now, I see room for improvement, and if we adopt the documentation strategy I propose, many other concerns will be addressed automatically.

Example

IMO here is an example on how documentation should like: https://docs.divio.com/en/latest/index.html

It is very clear what your goal is, either you discover the software, or your configure it, or you extend it. In any cases you know where to go.

I do not feel this separation of roles in the current docs. For instance we have a installation sub menu in Getting started, but we also have a docker main menu which is confusing if we want to install using docker. Also we have an advanced main menu, advanced what ? this isn't clear enough.

Maybe we could talk about this in Slack to make it more interactive, since they are a lot of data to process and I cannot always answer with comments as long as this one. Also it would be easier if we all share the same knowledge of the paper I use to describe my proposal.

Cheers :beers:

[benhaynes]

Thank you for taking the time to write this out so clearly @jooola!! This is a great and actionable list of feedback, but I do have a few questions/points to cover:

Tutorials vs How-Tos

I understand the descriptions of each of these, but I'm still having a hard time understanding the true delineation here. For instance, in your examples, if you rephrase this tutorial and write it as "numbered steps"... isn't it basically a "How To"?

Before: Installing Directus with Nginx and Mariadb
After: How to install Directus on Nginx with Mariadb

Third-Party Tutorials

The problem with posts on medium is that they are fixed in time. A medium post will not get updated as often as the documentation, which could keep the tutorial up to date.

I get this argument, and would love to keep everything in one place. But to your point on keeping things updated — how does this work across versioning? It seems that each tutorial would be based on the specific Directus version when it was published. Not sure if VuePress has versions built in... but it seems like it makes sense to keep all those tutorials tied to a time/version.

Also, would you imagine bringing in all/any video tutorials manually into the Docs too?

Summary

Generally I agree with everything you mentioned here — and the only reason we're not focused on it is that we have such a small (OSS) team, and have to get things stable as a priority. Also, with some new App changes coming in the next few weeks, it doesn't make sense to update all the screenshots now, only to redo them when v9 is released.

I think a good next step (after answering the first question here) is to propose a new hierarchal structure for the Directus Documentation. This can be as simple as a nested tree-view... but where would be the best place to create that? Here? Google Docs? Is that something you're interested in helping draft?

Thanks again!! ❤️

[jooola]

Thank you for taking the time to write this out so clearly @jooola!

My pleasure !

I understand the descriptions of each of these, but I'm still having a hard time understanding the true delineation here. For instance, in your examples, if you rephrase this tutorial and write it as "numbered steps"... isn't it basically a "How To"?

The main difference I understood from the whole paper, is that tutorials are more learning oriented, and how-to are problem oriented (see the picture with the 4 parts in the first posts).

What it means is that a new comer will what to learn how it works. Learning is enjoyable when everything works as expected. So tutorials needs to be bullet proof, a easy to read, without any distraction, help the user from start to end.

As new comers I want to spin up a directus suite and start playing with it in no time. Once I got the hang of it, I want to go further, and here comes how to guides into play.

How to guides aren't bullet proof. They tend to help to achieve a single task. So we don't need to take the use by the hand and explain start to begin, just the few steps required to solve the problem.

I get this argument, and would love to keep everything in one place. But to your point on keeping things updated — how does this work across versioning? It seems that each tutorial would be based on the specific Directus version when it was published. Not sure if VuePress has versions built in... but it seems like it makes sense to keep all those tutorials tied to a time/version.

I opened a ticket regarding versioning. I think we only need to version docs on major releases, since breaking changes only occur then.

See directus/docs#308

Also, would you imagine bringing in all/any video tutorials manually into the Docs too?

Videos could be used to help users to learn before doing, but this means that when users want to gets his hands dirty, a written tutorial must be available.

I feel videos can be useful, but only as introduction to the product, or present a part of the project.

Generally I agree with everything you mentioned here — and the only reason we're not focused on it is that we have such a small (OSS) team, and have to get things stable as a priority. Also, with some new App changes coming in the next few weeks, it doesn't make sense to update all the screenshots now, only to redo them when v9 is released.

Agreed.

I think a good next step (after answering the first question here) is to propose a new hierarchal structure for the Directus Documentation. This can be as simple as a nested tree-view... but where would be the best place to create that? Here? Google Docs? Is that something you're interested in helping draft?

I think a branch could be enough. I can start writing the structure yes. I'll propose a PR in the next days.

Once the new documentation is almost ready, we can start thinking on how to keep the old docs in a v8 branch and use master for all latest versions.

[benhaynes]

Thanks for the quick and thoughtful response! I agree with all of this...

Let's draft a simple text-only nested hierarchy before diving into a full PR... that will make it easier to edit and iterate through. We could just use a bullet list here on this GitHub thread, and edit that comment to keep it updated.

Of course, we're not against PRs either! :)

[rijkvanzanten]

From what I can tell from the shared link, a tutorial could be treated as a story-driven collection of how-to's, like _Setting up a new Directus Project_, while a how-to is a step-based "how to get to goal X" like _How to configure whitelisted asset sizes_. It seems like the difference is the tone of voice and structure of the content, where a tutorial is more friendly and explains a little more about the concepts around the things you're dealing with, while a how-to is very: 1. go here, 2. add this, 3: profit

[benhaynes]

Yeah, and I like the idea of building these out as: Tutorials often contain a set of How-To's that give more detail on specific processes in the discussion.

[Vadorequest]

I recently have redone my own documentation at https://unlyed.github.io/next-right-now/. I didn't follow any kind of guide, just my own thoughts.

https://unlyed.github.io/next-right-now/

Here is how I split up my doc, maybe it'll be some help to you, maybe not. I haven't read the whole thread. But a quick look there could give you some ideas. (even though I find the current docs really good and organised, most of the things I didn't find are... things that aren't documented at all 😅)

What I really took special care is the beginner workflow, big buttons on the bottom to help go through the next step, go back, link concept pages with related stuff, etc.

Also, any kind of re-structuring should take versioning into account, as per https://github.com/directus/docs/issues/308