TOC best practices

[Mpdreamz]

Our current post-migration script puts everything in file blocks with children:

 - file: observability/get-started.md
        children:
          - file: observability/get-started/what-is-elastic-observability.md
          - file: observability/get-started/create-an-observability-project.md
          - file: observability/get-started/quickstart-monitor-hosts-with-elastic-agent.md
          - file: observability/get-started/quickstart-monitor-kubernetes-cluster-with-elastic-agent.md
          - file: observability/get-started/quickstart-monitor-hosts-with-opentelemetry.md
          - file: observability/get-started/quickstart-unified-kubernetes-observability-with-elastic-distributions-of-opentelemetry-edot.md
          - file: observability/get-started/quickstart-collect-data-with-aws-firehose.md
          - file: observability/get-started/add-data-from-splunk.md
          - file: observability/get-started/get-started-with-dashboards.md

I think it be better if we prefer folder directives in the toc.yml.

 - folder: observability/get-started
        children:
          - file: index.md
          - file: what-is-elastic-observability.md
          - file: create-an-observability-project.md
          - file: quickstart-monitor-hosts-with-elastic-agent.md
          - file: quickstart-monitor-kubernetes-cluster-with-elastic-agent.md
          - file: quickstart-monitor-hosts-with-opentelemetry.md
          - file: quickstart-unified-kubernetes-observability-with-elastic-distributions-of-opentelemetry-edot.md
          - file: quickstart-collect-data-with-aws-firehose.md
          - file: add-data-from-splunk.md
          - file: get-started-with-dashboards.md

This will make it a lot easier to manually rename/move folders. It will also greatly help us in engineering to create refactor tools later down the line.

There are also some folders that contain a flat list of files but that get projected into complex navigation structures:

See: https://github.com/elastic/asciidocalypse/tree/add-docs-content/docs/docs-content/docs/solutions/observability/apps

and its TOC:

https://github.com/elastic/asciidocalypse/blob/add-docs-content/docs/docs-content/docs/solutions/toc.yml#L17C7-L83

I personally find these very hard to navigate and would prefer more deeply nested folders grouping things logically in folders to match their logical grouping in the TOC.

Instead of creating these groupings using file names folders work better:

• We can always flatten files in the output including folder names if we decide to limit folder depth.
• Renames are easier just rename the folder, no need to guess if a source file name pattern is intended or not.

[reakaleek]

Q: What are your thoughts on creating a toc.yml for every folder?

When I saw the top-level toc defintion, I thought it looked really easy and that every folder could benefit from it.

[reakaleek]

Benefits:

• If you move a whole folder, you only need to update the folder name in the parent toc.
• every toc is contained to it's children and won't affect sibling folders.
• ...

Downsides:

• ?

[Mpdreamz]

I think restricting the places where people can define navigation to a single source (or TOP level toc's only for very large TOC's) is a feature IMO.

It's a holistic overview that yes may be large but requires very little cognitive overhead.

If you move a whole folder, you only need to update the folder name in the parent toc.

You'd have to mark it removed in the old parents toc and add it to the new parent toc, that's three places to remember to update.

[lcawl]

Instead of creating these groupings using file names folders work better: We can always flatten files in the output including folder names if we decide to limit folder depth.

My two cents is this is fine as long as (1) we're very clear in the contributor guidelines about how that first file gets moved up to be the nav page for that folder (which I think is how docsmobile worked too, so internal folks should be used to it), and (2) we don't let the nested folders ill-affect our slugs.

Q: What are your thoughts on creating a toc.yml for every folder?

We kind of did this in the kibana repo (i.e. branches of the tree are defined in many separate folders). I found it a little confusing sometimes remembering how to ensure branches got picked up (it felt like you had to kind of hop backwards through the nested folders to see how/where it was being included). So if that proposal goes ahead we'd again need to be very clear for all our contributors about how to ensure all the branches are grafted to the trunk of the tree.