Create a clear space in docs hierarchy for the task-based docs

[thampiotr]

Currently, we have the following top-level hierarchy:

We don't have a dedicated place to put the task-based documentation. Existing top-level sections seem to overlap.

This issue proposes to have the following top-level sections instead:

• Get started - should include how to quickly install the agent and get hands-on experience. There may be some overlap or links to other pages, but the difference is that "get started" here is dedicated for the new users who are onboarding. We may go less in-depth in these pages and showcase the features and advantages of the Agent.
• Concepts - learn the concepts of the Agent used throughout the documentation.
• Tasks - pages dedicated to performing specific tasks and achieving a desired outcome. There can be many of them, these should be production-ready and contain best practices and recommendation. They are low level of detail, with Reference pages being the only ones more detailed.
• Tutorials - pages dedicated to learning - usually covering more ground than Tasks, may not need to be production-ready. It's a good place to go to after you've done Get Started section and want to prototype something. After completing a tutorial, the user should be able to dive deeper using Tasks section or Reference.
• Reference - remains unchanged. The most detailed docs we offer.
• Release notes - unchanged.

Once we have a broad consensus on what sections we want to have, we can assign the existing pages to correct sections.

[thampiotr]

@clayton-cornell and @ptodev, I would very much like to hear your opinion on this proposal and what alternative do you think we should consider.

[mattdurham]

Would this create a more nested hierarchy?

[clayton-cornell]

Another thought... split off or at least separate the River-specific concepts from how to use Rive in Agent. Iv'e been tinkering with this already (but no concrete results). There's lot of overlap and "mushing together" of River and Agent in the current Concepts and Configuration language sections.

[thampiotr]

Would this create a more nested hierarchy?

@mattdurham not really, because we mostly move things around on the same level where they are. I think maybe the "Monitoring" section would become Task-based topics instead.

split off or at least separate the River-specific concepts from how to use Rive in Agent

@clayton-cornell that would make sense, I agree - we could start by just splitting it into separate pages and making sure we talk about River more generally and then have a page on how Agent uses River. I think that maybe that change can be done separately from this issue.

[ptodev]

I've been thinking of adding a "When to use Flow" section, which compares the Agent to similar products. For now I'm planning on adding subpages to "When to use Flow" for Collector and for Prometheus Pushgateway. Where should this sort of content go, according to the proposed structure?

The proposal states that "Tutorials" will "more ground than Task", but also that after "completing a tutorial, the user should be able to dive deeper using Tasks section". I don't understand which one is supposed to be more detailed - Tutorials or Tasks?

I personally think there are two types of users:

1. Users who want to read detailed step by step instructions with more handholding
   • Those users will enjoy docs in the same style as our current Get started docs.
   • These are usually beginner users with time to spare.
2. Users who want to just see an example of an Agent in action, a short explanation of why it is configured that way, and what it is doing.
   • Suitable for time starved users, or the ones who have already completed the detailed tutorials and don't need everything explained in detail to them.

IMO we should not be writing too many detailed docs with verbose step by step instructions. For example, we should not spending too much text on "substitute this variable with this", or repeating descriptions of an argument which are already described in the reference docs. After the users have grasped the basics in the detailed step by step docs, they will want to read more complicated examples without the extra verbosity. Keeping verbosity to a minimum will also make it easier to write those docs.

[thampiotr]

Where should this sort of content go, according to the proposed structure?

Getting started - you want to choose whether you want to use Flow while getting started.

I don't understand which one is supposed to be more detailed - Tutorials or Tasks?

Tutorials can cover more ground by more superficially setting up a more things, for example, it could cover setting up logs, metrics and traces, without SSL, using local docker containers for DBs or Grafana Cloud as an option. Tasks would go more in-depth on a more narrow topic, for example, setting up logs collection in a k8s cluster.

I personally think there are two types of users ...

There's probably more, but if we use the two types, we would have users 1 would look into get started and then tutorials section and users 2 would be looking into tasks section (and maybe sometimes to reference section too, as we have examples there as well and I'm fine to leave it like this).

IMO we should not be writing too many detailed docs with verbose step by step instructions. For example, we should not spending too much text on "substitute this variable with this", or repeating descriptions of an argument which are already described in the reference docs.

I'm not suggesting we do that. The tutorials section maybe would be a place for this kind of content, but I think we shouldn't have too many tutorials and instead have full reference coverage and decent task-based docs coverage that helps people discover what reference pages to even go to. Right now there appears to be a lot of demand for task-based docs, because our reference pages are likely hard to digest.

[ptodev]

Thanks for the clarification! Sounds good to me. IIUC:

• Tasks will contain a lot more articles than Tutorials?
• Tutorials will be just for grokking the fundamentals. We expect advanced users only to read them at the start of their Agent journey.

I'd like the Tasks articles to be:

• Not paraphrasing things which are already mentioned in the reference pages, such as default values and the meaning of the arguments.
• Not showing step by step how to create each block individually. Instead, I'd like them to show the full River config at once.
• Ideally, it'd help to include architecture diagrams visualising what the task is going to do. Those diagrams should look in a consistent way across articles.

[thampiotr]

Tasks will contain a lot more articles than Tutorials?

Indeed. I expect tutorials to be more like additional learning resource after Getting Started.

I agree with all the principles that we should use for Tasks articles. I'll try to capture the purpose of each section in some meta-document in the actual PR.

[spartan0x117]

Either way I think we should stay consistent with the Writer’s Toolkit descriptions of Tutorial and Task docs 😃

[clayton-cornell]

Maybe we could use some additional info on the difference between a Task and a Tutorial beyond what's in the Writer's Toolkit:

• Task: Provides numbered steps that describe how to achieve an outcome.
• Tutorial: Provides procedures that users can safely reproduce and learn from.

A task topic should provide the information a user needs to do something specific. They should be focused on a single thing... a task in it's purest definition. It is limited in scope and focuses on guiding the reader through a specific process. An example of a task-based topic would be something like one of the installation topics. They do a single task, and provide just enough information to do an install and nothing more. They don't dive into the tangential concepts or explain at length... it's just run this command.

A tutorial should provide a learning experience. It's more and "end-to-end" series of tasks that you follow to achieve a measurable result. A tutorial should contain explanations, examples, etc. that help the reader not only do the thing, but understand why, and how it works. As @ptodev said, groking the fundamentals with helpful diagrams, visualisations, and so on.

[tpaschalis]

This sounds good to me on a surface level, but I'd defer to @clayton-cornell 's opinion here.

One thing that I'm not sure; does the "Configuration language" section go in the Concepts page?

[thampiotr]

One thing that I'm not sure; does the "Configuration language" section go in the Concepts page?

I would suggest that yes, at least for the first iteration of this.

[thampiotr]

I've drafted the definition of the sections in here: https://github.com/grafana/agent/pull/6031/files

After merging the above, the next step will be to actually do the reorg using the existing documentation pages. We'll put existing pages in their best fitting new categories, even if they're not 100% compliant to start with - we'll be cleaning them up afterwards.