Description
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