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

Edited by toscalix