Altinn / altinn-decision-log

Log for architecture and design/ux decisions across Altinn teams and products
0 stars 0 forks source link

Standardize structure on Diataxis for product documentation #5

Closed nkylstad closed 2 months ago

nkylstad commented 6 months ago

Status

Accepted

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:

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.

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

Yep, I agree on both counts:

altinnadmin commented 6 months ago

Yes, those are very interesting topics...

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

altinnadmin commented 5 months ago

Accepted 30.05 by the architecture team.