Feature request: Modular navigation indexes (Generate Diataxis pages from Home)

[ricab]

With the Diataxis scheme, the Home page should include sections for each of the four categories (see template). IIUC, each of those category headings should link to a page that contains the summary line, along with a tree of links. That tree of links should mirror the corresponding branch in the navigation page (e.g. https://multipass.run/docs/how-to-guides).

These pages currently need to be created from discourse posts that repeat the information in the navigation pane. They need to be kept in sync manually, which is error prone. Since all the information needed to produce these pages is present in the post for the home page, it would be nice to have them generated automatically.

[nottrobin]

OK here's my understanding of what you're saying, tell me if I'm wrong.

Daniele has specified that all documentation authors should start grouping documentation into 4 categories (following the Diataxis framework):

• Tutorials
• How-to guides
• Reference
• Explanation

Each of these categories should have an index page, which you've termed a "homepage", which displays a list of all items under that section.

Separately, there's a left-hand navigation which lists all documentation in all the categories. The navigation is therefore simply the contents of these 4 index pages put together.

This means that at the moment, you're having to duplicate the list of documents between the index pages and the relevant part of the navigation.

So you're asking if we can come up with a way that the list of documents under each category (e.g. the list of how-to guides) can be written in only one places, and then automatically pulled in the other place, to avoid extra work and potential mistakes.

Is that correct?

[ricab]

Hi @nottrobin,

Is that correct?

Mostly, except I was asking for the rendering to be the other way around :slightly_smiling_face: Let me layout my reasoning, and please correct me if there is anything wrong with it.

We are trying to adhere to the Diátaxis framework, whose rendition at Canonical requires a homepage, following the template above. The homepage is the root entry point to the documentation of a product (the one in https://multipass.run/docs in our case). As per the template, the home page needs to link to an index page for each of the 4 categories, containing a tree of links to the documents therein.

These category pages should therefore mirror the contents of the navigation pane. But that pane is generated from a navigation table that determines the contents and structure of the documentation. The navigation table has all the info needed to generate the category pages, except for a generic (static) short description of the category (e.g. "Step-by-step guides covering key operations and common tasks").

For the time being, we created those category pages manually. As you might expect, the next day we added new documents, the pages went out of sync... IIUC, this problem will be common to all docs pages generated from discourse and following Diátaxis patterns.

We have already been editing the navigation table and having stuff generated from it, so I thought it could be maintained as the single source of truth for this. The addition I requested here was therefore to generate category pages from the discourse post corresponding to the home page, which is where the navigation table is defined. But there might be reasons I am unaware of to do it the other way around and generate the navigation pane from the category pages, as you suggest. I guess that would work too, but I do like that we can edit a single discourse post to move things around.

[ricab]

Hey @nottrobin, @sowasred2012, please let me know if anything is still unclear here or if there is any other input you need from me to address that question label. Thanks!

[mtruj013]

@nottrobin @sowasred2012 what are the next steps for this? Thanks

[nottrobin]

I think it need scheduling somewhere and to have a spec. It's a significant piece of work. It would be perfect to give to a documentation squad if such a thing existed (cc. @cristinadresch)

[nottrobin]

I've created an issue in the systems squad to write a spec for this. Once we've planned the work we'll implement a new system in the discourse module and roll it out to multipass.run.

This is on the systems squad backlog down at row 11. Which means we might get to it in a couple of months.

[carkod]

This sounds like a very specific thing about documentation not so much multipass.run site. Shoulnd't this be brought up to @danielmutis