Decide on default conventions for information architecture

[ADubhlaoich]

Overview

As a documentation contributor, I want clear guidelines, So I can update documentation appropriately.

As a user, I want a consistent reading experience, So I can navigate product documentation with prior knowledge.

Description

The NGINX DocOps team represents lots of perspectives when it comes to structuring technical information.

We have strong opinions that are loosely held in favour of consistency.

Our information architecture has developed holistically, but there are gaps representing things we have never made formal decisions about, only known through informal discussion.

We need to explicitly discuss these items. As a team that works in open source, we will do so in public GitHub discussions, and document them accordingly.

Issue #414 concerns ADRs for information architecture, and is where decisions will primarily be recorded.

Some decisions will additionally inform changes to existing artifacts, such as our Hugo archetypes or style guide.

Each discrete item discussed will have a timebox, and the discussion itself will be recorded as part of the changes.

Tasks

These items do not have checkboxes as this is expected to be an ongoing task, in contrast to a single work effort.

• Create a GitHub discussion for an information architecture convention
• Include this issue in the discussion description for context, and set a deadline for the discussion to end
• Add a clear "Next step" when closing the discussion, such as creating an ADR.

Acceptance criteria

• The user has a consistent browsing experience across the NGINX portfolio
• The user can find the decisions for any identifiable documentation pattern
• The user is able to contribute to documentation with the context gained as a reader

[ADubhlaoich]

Initial thoughts for items we need to record, which may or may not be represented by a discussion.

• Use of the Diataxis framework
• Standard pages and sections for all documentation sets, such as "Support"
• Use case-driven collections of content, and the order in which they appear
• "Get started" vs "Quickstart" as a page name and type
• "Get started" as an overall design pattern / section
• Delineating "Release notes" and "Known issues" or representing them in one content artifact
• Renaming "Releases notes" to "Changelog"

Some of these have been discussed internally, so might be candidates for jumping straight into an ADR without discussion.