Content structure
Background
Before adding new content to the wiki for the release, we need to agree in some kind of content structure, so can have a design that supports the goals of the documentation. This structure should have the following characteristics:
- It should be tool independent. We currently have a wiki and git based documentation. We might add in the future a website, a blog tool and others. The content structure should benefit from the features this tool might bring but should not be determined by then.
- It should consider the target audience. For each target audience, there should be a well defined critical path when walking through the contents. We will design contents for at least the following audience:
- Contributors: core contributors/maintainers and occasional contributors.
- Users: integrators and developers (for now).
- The rest of the world: those who know about BuildStream and those who don't.
- The structure should consider the maintenance effort. In fact, this effort is as critical as the creation effort. To make it simple, we will consider three type of contents:
- Static: content that is not expected to change frequently, i.e. project principles or Manifest.
- Dynamic: content that is expected to change frequently, once it is consider completed the first time, i.e. roadmap page.
- Replaceable: content that will be replace by new content when a specific event occurs, i.e. Feature page of a specific released version. Do no mistake replaceable with erasable. In theory, we will not erase content by design.
Task description
The content structure proposal will require:
-
Diagram with the content structure. -
A short explanation of the structure diagram and a legend. -
Critical path diagram for every target audience. -
Explanation of the critical path diagram and its impact in the content structure. -
Main discussion points, based on the need to reach a consensus for the release. -
Next steps.
Once the Content structure proposal is merged in the alignment repo, the following activities will need to performed:
-
Add links to diagrams in the proposal itself. -
Create the mail that will be sent to the mailing list, restricted to the contents related with the release, as detailed below. -
Send the proposal to the mailing list. -
Get consensus.
The following step will be start the creation of the Contents: (add the ticket number).
The proposal sent to the mailing list will be restricted to:
-
General view of the contents. -
Release related contents. -
Reference to the Content structure proposal.
Associated MR: !2 (merged) and !3 (closed)
Acceptance Criteria
- Link to the proposal sent to them mailing list: https://mail.gnome.org/archives/buildstream-list/2018-August/msg00032.html
- Link to the Content structure proposal that supports the proposal for the creation of the release oriented content subset: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/content_structure_proposal_description.md
Edited by toscalix