|
Hi all,
it is time to start the creation of the contents related with the release. In fact we are already a bit late late but hey....
The following proposal is based on what I have designed as a kind of high level "content architecture" to drive the content creation, contribution management and maintenance. Those of you who want to dig deep in the Content Structure, please read the full proposal[1]. Do not forget to open the diagrams in parallel, it will help you. Some the content below is extracted from that long document.
### Target audience
Based on the BuildStream target audience, I propose, for to consider only the following target audience, for simplicity:
* Those unaware of the existence of BuildStream (99%)
* Those aware of the existence of BuildStream (1%)
* BuildStream users (0.1%)
* BuildStream contributors (0.001%)
In general, when I refer to users, I will also be referring to contributors. As the project matures, so the content, it would be ideal to segment some of the above target audiences even more.
### Tools
Initially I propose to work with what we have:
* Gitlab:
* The current guide.
* Key files in repos (specially buildstream.
* The GNOME wiki
We will focus initially on creating the content on Git using gitlab capabilities for it, together with the new domain, buildstream.build. On the wiki, we will focus on having a good "buildstream wiki home page" and improving a little the current content in other important pages. With this approach, we expect to get ready for when a web comes reducing the effort that keeping the information on the wiki and git on sync.
One risk we need to strongly consider is related with the links strategy. There are several ways to approach this issue and it will be a matter of policy. Breaking links might throw to the garbage, not just internal references, so pre-defined critical paths, but also external references to our content.
### Timeline
Ideally, we will have those contents directly related with the release ready for the Release Date (RD) and the rest would be done little by little, having ELCE 2018 as a key milestone. The upstream team will dedicate some effort to this action between RC and Gold Master Declaration (GM).
### Content management
Since this is an Open Source project, the best way to receive meaningful contributions in this area is to define the structure, create minimal contents based on the structure for the pages listed below and provide the community some guidelines on how to contribute (MRs). This will be the approach I propose to follow vs the approach in which contents are only published when finished.
As you already know by now, if we want good contents we will need to be as serious about them as we are about code. We have a good example on the current guide. I propose to create a web repo in nosoftware subgroup including a bug tracked about it. A proposal on how to relate this ticketing system with the existing ones and the current Documentation label will be sent to the list.
A key part of the maintainability story when it comes to content are labels/tags and URLs. We will need to pay special attention to them and create very specific policies on how to create and update those tags and URLs.
### Content to start with.
Having the mentioned structure in mind[1], these are the contents I propose to concentrate on the coming weeks, related with the release:
* Landing page: root page for BuildStream outcomes (releases + master)
* Project page: root page for all the community project related content
Code and metadata:
* Download page: page including links to what should be downloaded by users (releases)
* README file: default repo file displayed by gitlab.com
* COPYING (LICENSE) file: repo file containing the licenses
* NEWS (Digested release notes) file: fine containing the digested/purged release notes
BuildStream Outcomes:
* Portfolio page: page describing the different outcomes BuildStream produces.
* BuildStream Master: Description of what is Master and who is for.
* BuildStream releases page: Description of the releases, links to them, explanation about the nomenclature used on releases.
* BuildStream 1.2 feature page: description of what is new in the current release.
* BuildStream 1.2 deployment and installation howto page: instructions on how to install or deploy the release.
* BuildStream 1.2 known issues: issues that users might find and workarounds. This page is related with the issue tracker.
BuildStream description:
* BuildStream in Detail: architectural/technical description of the tool. Enumeration of the key features. In the future we will link those features to pages describing them, including examples.
* Glossary: terminology used in the project.
* FAQ: structured questions/answer page. It will include at least the basic set of questions for people unaware of BuildStream and also for those that, after installing BuildStream, require community support to move on or dig in.
Processes Management
* BuildStream roadmap: with each release, we need to have ready the information about the following cycle i addition with the current one.
* BuildStream Release howto: we need to start documenting the specific activities related with the release, since the process will become more and more rich overtime.
The above pages will be structured based on pre-defined critical paths. You can learn about them at the Content Structure document[2] and diagrams [3][4].
Again, the initial goal is not to have very reach content but well structured. Then we can increase its amount and raise its quality based on users feedback and our own experience using it. As you can see, this proposal has quite some work associated so, the sooner we start...
I would like to finish recommending you go over the Content Structure[1] since some of the questions that this proposal might raise can be answered there. Laurence is helping me to polish the document so there might be MR open to fix typos.
[1] Content structure proposal: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/content_structure_proposal_description.md
[2] Content structure diagram: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/BuildStream_Content_Structure_diagram.pdf
[3] Critical path: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/BuildStream_Content_Structure_critical_path.pdf
[4] Critical path per target: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/BuildStream_Content_Structure_critical_path_per_target.pdf
Best Regards
--
AgustÃn Benito Bethencourt
Principal Consultant
Codethink Ltd
We respect your privacy. See https://www.codethink.co.uk/privacy.html |
