Standardize structure on Diataxis for product documentation

[nkylstad]

Status

Accepted

Context

What is the issue that we're seeing that is motivating this decision or change?

Each product is in charge of their own documentation, but there are no guidelines or frameworks that we use to standardize the documentation. Diataxis has been suggested as a framework that we can use to structure our documentation.

Decision

What is the change that we're proposing and/or doing?

Use Diataxis as a basis for the structure and content of our documentation. In addition to the 4 main sections that are outlined there, I have proposed a few more. Proposed sections pr. product:

• About (the product)
• What do you get (high level introduction)
• Getting started/tutorials (from Diataxis)
• User guides (from Diataxis)
• Reference (from Diataxis)
• Explanation/articles (from Diataxis)
• News and/or plans

Consequences

What becomes easier or more difficult to do because of this change?

Each product must re-structure their documentation to fit into these categories. The content of the documentation should also be considered, as much of what we have now does not fit into just one category. Some of our documentation will need to be split up and re-written with the specific categories in mind.

Diataxis provides very clear guidelines on what type of content should be present within each of the 4 main categories. This should make it easier to create new documentation in the future, and make it easier to know where to place it. It should also make it clear what kind of documentation we need to provide when we deliver new features.

Finally, making this change should ensure that our documentation is more of a unit. Our users, for whom we write the documentation, will get a recognisable structure across our documentation. In the future, this may also allow us to document more on how the products work together as packages.

[martinothamar]

Big fan of Diataxis 🏅

Could we define "product" here? I'm working on improvements monitoring docs in https://github.com/Altinn/altinn-studio-docs/pull/1644 and I don't think I would define monitoring as a product, yet I have tried to structure the contents in relation to Diataxis, in the sense that there is a quick start page (getting started/tutorial), and a couple of pages used for reference in relation to specific issues (such as configuration), and hopefully eventually we will have some user guides for specific goals (such as custom OTel exporters etc)

I also wonder what is meant by "sections" here. Do you think we should have a folder per category listed? Or could for example the "About" and "What do you get" sections be combined into a single page (the root page in the monitoring case)?

[lvbachmann]

Finally, making this change should ensure that our documentation is more of a unit. Our users, for whom we write the documentation, will get a recognisable structure across our documentation. In the future, this may also allow us to document more on how the products work together as packages.

From a marketing standpoint, this would be much appreciated. For finding this recognisable structure, I believe the questions raised in this section of the Diátaxis documentation are something that we need to address. If you have already done these kind of assessments, I would love to hear about them.

[nkylstad]

Big fan of Diataxis 🏅

Could we define "product" here? I'm working on improvements monitoring docs in Altinn/altinn-studio-docs#1644 and I don't think I would define monitoring as a product,

In "product", I mean our official (and probably some un-official) Altinn products. F.ex. Altinn Studio, Authorization, Broker, Correspondence, etc. Will specify this more clearly in the issue 😊 It's unfortunate that all of the different products have their documentation on a page called "Altinn Studio Docs" when Altinn Studio is just one of the products, but it is my understanding that that is also something we are working on changing. (cc: @altinnadmin )

So in the case of monitoring, that would belong within the Altinn Studio product. I have PR open where I will move all content from the apps top-level folder (Apps is not a product, but a part of Altinn Studio) to the altinn-studio top-level folder.

I also wonder what is meant by "sections" here. Do you think we should have a folder per category listed? Or could for example the "About" and "What do you get" sections be combined into a single page (the root page in the monitoring case)?

In the same vein as above, the sections would then apply to the top-level products, and not its features. The features would then need to fit into the different sections.

An alternative way of structuring the docs could be to turn focus more on the features themselves, and then apply Diataxis within each feature. However this would mean that the recognisable structure within each product would be less uniform.

[nkylstad]

Finally, making this change should ensure that our documentation is more of a unit. Our users, for whom we write the documentation, will get a recognisable structure across our documentation. In the future, this may also allow us to document more on how the products work together as packages.

From a marketing standpoint, this would be much appreciated. For finding this recognisable structure, I believe the questions raised in this section of the Diátaxis documentation are something that we need to address. If you have already done these kind of assessments, I would love to hear about them.

Yes, this is definitely a challenge we need to address, and not at all trivial. One assessment/suggestion that has been made (independently of this suggestion to re-structure the docs) is to develop landing pages that cater to different kinds of users. So that the structure of the docs themselves are relatively uniform, but the entry point for the user is what guides them to what is relevant for them.

[bjosttveit]

Would it also make sense to move the changelogs for app-lib and app-frontend from the Community-category into this structure? https://docs.altinn.studio/community/changelog/

[altinnadmin]

Could we instead use GitHub releases for the changelogs themselves, and just link to them from news-section or a blog when larger changes lands for a product?

We see that the changelogs "pollutes" both search results and Altinn Assistant.

[bjosttveit]

I am mostly thinking about the breaking changes and migration guides, which we definitely need in the docs.

I agree that the "what's new" pages are unecessary when we aleady have GitHub releases, we don't use docs for this anymore, so maybe we could just delete these if they just cause noise?

[nkylstad]

Yep, I agree on both counts:

• migration guides should be moved into the relevant product. In this case I guess it's just Altinn Studio that has these migration guides in the community category. Could probably create a section for "version upgrades" in altinn-studio/guides that includes the migration guides?
• Overview of delivered functionality in a given release should be documented in the Github changelogs 🙌

[altinnadmin]

Yes, those are very interesting topics...

• Migration to next major version (breaking changes)
• Migration from Altinn II to Altinn 3 APIs (helping SBS and service owners)
• Migration from "old way" to "new better way" (building understanding)
• Informing about "news" and cool releases, where should we do it? Is the technical product documentation "silo" the best place or should we use a common blog or something?

Doing these things the same way across products will be important.

[altinnadmin]

Accepted 30.05 by the architecture team.