GNOME.org
 

Re: [BuildStream] Contents for the BuildStream 1.2 release

Hi,

On Tuesday, 28 August 2018 20:00:36 WEST Agustín Benito Bethencourt wrote:

Hi,

This is a hands up of the progress in this field, which is important for the coming release.


Due to limitations when it comes to rendering/publishing pages from repos located in subgroups, we have moved 
the website project from the nosoftware subgroup to the BuildStream group. We are expecting at some point 
that Gitlab fixes this limitation: https://gitlab.com/gitlab-org/gitlab-ce/issues/30548

This has had several consequences:
* We have adjusted the project members roles to what they were before the movement.
* One of the labels used in this project was a subgroup label (shared with other repos at nosoftware. This 
label has been duplicated in the website repo instead of promoting it as group label to avoid appearing in 
buildstream project.
* The milestone page is now empty although BuildStream group milestones can still be selected in issues and 
MR.

It seems that we will be able to erase the repo buildstream.gitlab.io created by Sam T. It has nothing to do 
with the documentation.



On Saturday, 11 August 2018 18:22:59 WEST Agustin Benito Bethencourt via BuildStream-list wrote:

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.


The current plan is to use Gitlab to create a simple web for the project under buildstream.build We have 
created a new repo under nosoftware subgroup with a structure mostly inherit from the BuildStream group and 
nosoftware subgroup. The labels match the Topics in which we have divided the content structure.

Link: 
https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/content_design/BuildStream_Content_Structure_diagram.pdf
 



### 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).


The current plan is to have this web with the minimum set of pages ready for the release. Next Monday to 
Wednesday we will be focused on this.


Once moved, the repo render the pages. Tiago is working on it. The idea is to have the technical aspects of 
the website ready this week in order to concentrate next week on the content.




### 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].


We have started this work. You can follow it here: 
https://gitlab.com/BuildStream/nosoftware/website/boards/721015?=


New link: https://gitlab.com/BuildStream/website/boards/721015?=



All the help we can get from any of you is welcome. We have way more to do than capacity.


Best Regards

-- 
Agustín Benito Bethencourt
Principal Consultant
Codethink Ltd
We respect your privacy.   See https://www.codethink.co.uk/privacy.html
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]