DOCPR-663: add section on Diátaxis to the style guide

[edibotopic]

PR for Jira ticket DOCPR-663, which aims to include a brief reference to Diátaxis in the style guide.

Diátaxis is the foundation from which much of Canonical's product documentation is built. The form and style of a page of documentation is influenced by the Diátaxis category in which it fits.

Given its centrality, a reader might expect to find a reference to this framework in the style guide.

This PR adds a brief section on Diátaxis to the top of the style guide. It mentions briefly:

• That Diátaxis should be used
• The four categories in Diátaxis
• How the categories can influence style
• A link to a more detailed resource (the Diátaxis website)

[giuliazanchi]

Hi @edibotopic , just sharing my thoughts here as well after our chat, hoping they can jumpstart a conversation.

I agree that this section should be short and concise and that readers should mostly refer to the main website for detailed information. Still, in my opinion, we could rephrase the last paragraph or perhaps include one of the Diataxis diagrams instead, such as the basic grid proposed in Documentation Workshops. I feel that the distinction and relationship between the four content types can be fuzzy, especially to new users, and providing a brief, though precise, reference (diagram?) in the style guide would be helpful.

[edibotopic]

Good points @giuliazanchi ! Of course, we want to be as clear as possible without devoting too much space in the guide to this topic specifically.

I'm open to the idea of a diagram as long as the diagram itself does not need too much explanation. Perhaps after including the diagram the paragraph you mentioned could be rewritten as that explanation.

[giuliazanchi]

@edibotopic the diagram I was thinking about is the one featured on the Diataxis homepage:

[edibotopic]

Thanks @giuliazanchi . I thought it might be that one.

My main concern is that to properly motivate and explain this diagram could be a substantial task within the narrow context of the style guide, as it introduces various conceptual distinctions (e.g., acquisition/application, action/cognition). Not all readers immediately grok these grid diagrams without an accompanying explanation.

Even with significant time/text invested someone might still struggle to distinguish a tutorial from a how-to and I'm not sure the style guide is the place to fight that battle.

Originally I only wanted to present the categories and indicate briefly how they could influence style. If the reader followed the link for more info that diagram would be one of the first things that they see, so I'm not sure if we need to show it in both places.

Let me think about how some of these ideas could be factored into a short rewrite.

[giuliazanchi]

I see your point; in that case, best to skip the diagram. To avoid misunderstandings or complications, I would perhaps even go as far as removing the examples in the last paragraph altogether so that readers must necessarily click the link to the official website to learn more.

Let's hear what other authors think about this section!

[edibotopic]

@giuliazanchi - we spoke in the green standup about this yesterday.

I had originally tried to explain some of the stylistic aspects of the categories briefly, raising the issue you had identified, which was that the descriptions might not be seen as complete.

I have revised the suggestion for conciseness. It now simply says that Diataxis should be used, what the categories are and then points to the official website.

Could you have a look, assign yourself as a reviewer and let me know if it's OK?

In the meantime, I will look for someone else to review.

[edibotopic]

LGTM with Nick's rewording. I agree that "specific style" is somewhat unspecific :) Thanks!

Thanks @giuliazanchi --- yup, I think we will go with that wording.