| ... |
... |
@@ -2,14 +2,14 @@ |
|
2
|
2
|
|
|
3
|
3
|
In the same way that a software product requires an architecture, the contents of a product do too, for similar reasons, being scalability and maintainability two of the important ones.
|
|
4
|
4
|
|
|
5
|
|
-Based on previous experiences managing Open Source projects (products) I would like you to evaluate the following proposal which I've called "Content Structure". As usual, I am open to suggestions when it comes to naming.
|
|
|
5
|
+I would like you to evaluate the following proposal which I've called "Content Structure". As usual, I am open to suggestions when it comes to naming.
|
|
6
|
6
|
|
|
7
|
|
-There are three diagrams[1][2][3] that support the current proposal. Please take a look at them while reading this document. One final document includes all of the three[4].
|
|
|
7
|
+There are three diagrams[1,][2],[3] that support the current proposal. Please take a look at them before reading this document. One final document includes all of the three[4].
|
|
8
|
8
|
|
|
9
|
9
|
|
|
10
|
10
|
### Content Units
|
|
11
|
11
|
|
|
12
|
|
-The structure is based on related "Content Units", a name used to avoid the association of any of those units with a specific tool, the concept of a "page" or a "file".
|
|
|
12
|
+The structure is based on "Content Units", a name used to avoid the association of any of those units with a specific tool, the concept of a "page" or a "file".
|
|
13
|
13
|
|
|
14
|
14
|
For example:
|
|
15
|
15
|
|
| ... |
... |
@@ -17,20 +17,19 @@ For example: |
|
17
|
17
|
* Two content units can be published initially in a single web page and, when they expand, separated into two.
|
|
18
|
18
|
|
|
19
|
19
|
|
|
20
|
|
-I will refer to pages or files only in specific cases.
|
|
|
20
|
+I will refer to pages or files only in specific cases. The "Content Units" are grouped by topics and related. The relation are simple and will be develop in future diagrams.
|
|
21
|
21
|
|
|
22
|
22
|
|
|
23
|
23
|
### Target audience
|
|
24
|
24
|
|
|
25
|
|
-Based on the BuildStream target audience, I propose, for simplicity to consider the following target audience when it comes to content design:
|
|
|
25
|
+Based on the BuildStream target audience, I propose for simplicity to consider the following target audiences when it comes to content design:
|
|
26
|
26
|
|
|
27
|
27
|
* Those unaware of the existence of BuildStream (99%)
|
|
28
|
28
|
* Those aware of the existence of BuildStream (1%)
|
|
29
|
29
|
* BuildStream users (0.1%)
|
|
30
|
30
|
* BuildStream contributors (0.001%)
|
|
31
|
31
|
|
|
32
|
|
-
|
|
33
|
|
-In general, when I refer to users, I will also be referring to contributors. As the project, so the content, matures, it would be ideal to segment some of the above target audiences.
|
|
|
32
|
+Inmost occasions when I refer to users, I will also be referring to contributors. As the project, so the content, matures, it would be ideal to segment some of the above target audiences.
|
|
34
|
33
|
|
|
35
|
34
|
Occasionally, the proposal or/and content itself might refer to the following subgroups:
|
|
36
|
35
|
|
| ... |
... |
@@ -41,7 +40,6 @@ Occasionally, the proposal or/and content itself might refer to the following su |
|
41
|
40
|
* Core contributors: those who contribute on regular basis, normally to specific/key areas.
|
|
42
|
41
|
* Occasional, sporadic, opportunistic contributors: the rest of the contributors.
|
|
43
|
42
|
|
|
44
|
|
-
|
|
45
|
43
|
This might provide a hint on further target audience segmentation we can define in the coming future.
|
|
46
|
44
|
|
|
47
|
45
|
|
| ... |
... |
@@ -57,25 +55,23 @@ Initially we will work with what we have: |
|
57
|
55
|
|
|
58
|
56
|
The structure is designed to be as "tool agnostic" as possible.
|
|
59
|
57
|
|
|
60
|
|
-We will focus initially on git based content, using gitlab capabilities for it. On the wiki, we will focus on having a good "front page" and improving a little the current content. 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.
|
|
|
58
|
+We will focus initially on git based content, using gitlab capabilities for it. On the wiki, we will focus on having a good "front page" and improving a little the current content. With this approach, we expect to be ready for when a web comes, reducing the effort associated to keeping the information on sync between git and the GNOME wiki.
|
|
61
|
59
|
|
|
62
|
|
-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 through to the garbage not just internal references, so out pre-defined critical paths, but also external references to our content.
|
|
|
60
|
+One risk we need to strongly consider is related with the links. There are several ways to mitigate the risk. Whatever measures we apply, they will be a matter of policy so proposals on the mailing list will be required to change them. Breaking links might through to the garbage not just internal references, so pre-defined critical paths, but also external references to our content.
|
|
63
|
61
|
|
|
64
|
62
|
|
|
65
|
63
|
### Timeline
|
|
66
|
64
|
|
|
67
|
|
-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.
|
|
|
65
|
+Ideally, we will have most of the content units directly related with the BuildStream 1.2 release ready for the Release Date (RD). The rest will be done little by little, having ELCE 2018 as a key milestone.
|
|
68
|
66
|
|
|
69
|
67
|
|
|
70
|
68
|
### Content management
|
|
71
|
69
|
|
|
72
|
|
-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 at least the essential units and provide the community some guidelines on how to contribute. This will be the approach I propose to follow vs the approach in which contents are only published when finished.
|
|
73
|
|
-
|
|
74
|
|
-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. We will 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.
|
|
|
70
|
+Since BuildStream is an Open Source project, a proven way to receive meaningful contributions in contents is to define the structure, create minimal contents according to that structure and point to missing content together with simple and clear policies on how to contribute. This will be the approach I propose to follow vs the approach in which contents are only published when finished.
|
|
75
|
71
|
|
|
76
|
|
-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 them.
|
|
|
72
|
+As you already know by now, if we want good contents we should be as serious about them as we are about code. We have a good example on the current guide. We will create a web repo in nosoftware subgroup including a bug tracked for the contents. A proposal on how to relate this ticketing system with the existing ones and the current Documentation label will be sent to the list.
|
|
77
|
73
|
|
|
78
|
|
-Except the front page of the wiki, we will focus initially on the release related content. Before ELCE 2018, we will put additional effort on the wiki.
|
|
|
74
|
+A key part of the maintainability story when it comes to contents 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 them.
|
|
79
|
75
|
|
|
80
|
76
|
|
|
81
|
77
|
### Criteria followed to structure the content units
|
| ... |
... |
@@ -86,9 +82,7 @@ Assuming the Open Source nature of the project and the fact that we are developi |
|
86
|
82
|
#### Expected content change rate
|
|
87
|
83
|
|
|
88
|
84
|
|
|
89
|
|
-Some content units will have a higher change rate than others. Separate them in different content units is essential to reduce in the future the maintenance effort. It also helps to decide which tool could appropriate for each unit too.
|
|
90
|
|
-
|
|
91
|
|
-For simplicity, I have considered the following groups:
|
|
|
85
|
+Some content units will have a higher change rate than others. Separate them in different content units is essential to reduce in the future the maintenance effort. It also helps to decide which tool could be appropriate for each unit. For simplicity, I have only considered the following groups:
|
|
92
|
86
|
|
|
93
|
87
|
* (almost) Static: content that is not expected to change frequently, i.e. project principles or Manifest.
|
|
94
|
88
|
* Dynamic: content that is expected to change frequently, grow overtime or have a limited life expectancy.
|
| ... |
... |
@@ -99,23 +93,22 @@ For simplicity, I have considered the following groups: |
|
99
|
93
|
#### Front page vs project and landing pages
|
|
100
|
94
|
|
|
101
|
95
|
|
|
102
|
|
-There are two main content units we will used as "root units" in terms of the proposed content structure:
|
|
|
96
|
+There are two main content units we will use as "root units":
|
|
103
|
97
|
|
|
104
|
98
|
* Project page.
|
|
105
|
99
|
* Landing page.
|
|
106
|
100
|
|
|
107
|
101
|
|
|
108
|
|
-I refer to them as pages, instead of units, because they are single pages and also because is a very common terminology.
|
|
|
102
|
+I refer to them as pages, instead of units, because they are single pages and also because the names are popular among those who develop FLOSS "products".
|
|
109
|
103
|
|
|
110
|
|
-Please be aware that these pages will not be designed as the BuildStream project front page (also common terminology). Until we have a web (hopefully for ELCE 2018) we will have a simple front page on the wiki, as today, which will be designed to die (erasable).
|
|
|
104
|
+Please be aware that these pages will not be designed as the BuildStream front/home page.
|
|
111
|
105
|
|
|
112
|
|
-The project page and the landing page might be moved to the future web, depending on design, effort and maintenance related decisions. Based on it, the current wiki front page (project wiki page in GNOME terminology) might change.
|
|
|
106
|
+The project page and the landing page might be moved to the future web, depending on design, effort and maintenance factors.
|
|
113
|
107
|
|
|
114
|
108
|
|
|
115
|
109
|
#### Outcomes as the most influential event
|
|
116
|
110
|
|
|
117
|
|
-
|
|
118
|
|
-Assuming the most common journey to become a maintainer (not the only one):
|
|
|
111
|
+Assuming the most common journey to become a maintainer (not the only one) being:
|
|
119
|
112
|
|
|
120
|
113
|
Humanity -> User -> Power user -> Occasional Contributor -> Core contributor -> Maintainer
|
|
121
|
114
|
|
| ... |
... |
@@ -123,9 +116,9 @@ at this point of maturity of the project, releases allow us to maximize the impa |
|
123
|
116
|
|
|
124
|
117
|
As the project matures and the number of users grow we might evolve our focus towards gaining contributors, for instance. The structure, with the support of the critical path definitions, should evolve too.
|
|
125
|
118
|
|
|
126
|
|
-In my experience, using the concept of releases as criteria for defining the content structure of projects that:
|
|
|
119
|
+In my experience, using the concept of releases as criteria for defining the content structure in projects that:
|
|
127
|
120
|
|
|
128
|
|
-* Need the kind of attention that leads them to find users with technical profile.
|
|
|
121
|
+* Need the kind of attention that leads them to find users with technical skills.
|
|
129
|
122
|
* Does not have a meaningful number of experienced technical product content creators.
|
|
130
|
123
|
* Cannot or do not want to heavily invest in promotion/marketing activities compared to development ones.
|
|
131
|
124
|
|
| ... |
... |
@@ -133,34 +126,34 @@ In my experience, using the concept of releases as criteria for defining the con |
|
133
|
126
|
.... work well.
|
|
134
|
127
|
|
|
135
|
128
|
|
|
136
|
|
-#### Use cases and sister projects
|
|
|
129
|
+#### Other user and sister projects
|
|
137
|
130
|
|
|
138
|
131
|
|
|
139
|
132
|
BuildGrid has been considered as a "sister project". Initially, it can rely of the current structure to minimize the effort required from their side.
|
|
140
|
133
|
|
|
141
|
134
|
Freedesktop-SDK can be considered explicitly in several units, like in Pr.1 D.1, D.4 and D.5 There is plenty of room for collaboration.
|
|
142
|
135
|
|
|
143
|
|
-Additional use cases can also be considered in several units. I hope you agree with me that the proposed structure leaves enough room to accommodate them. Otherwise, please let me know.
|
|
|
136
|
+Additional user projects can also be considered in several units. I hope you agree with me that the proposed structure leaves enough room to accommodate them. Otherwise, please let me know.
|
|
144
|
137
|
|
|
145
|
138
|
### Topic
|
|
146
|
139
|
|
|
147
|
|
-The content has been structured in 6 different groups based on topic. Some units might be part of several groups so please point out when you feel the grouping might be too controversial. this grouping helps to structure the proposal but it has no direct relation with how the final "pages" are linked in most cases. Please check the BuildStream_Content_Structure_diagram.pdf image[1].
|
|
|
140
|
+The content has been structured in 6 different topic groups. Some units might belong to more than one. The intention is to be clear, not accurate. The current grouping has a small impact on how the final "pages" are linked in most cases. Please check the BuildStream_Content_Structure_diagram.pdf image[1].
|
|
148
|
141
|
|
|
149
|
142
|
The topics are:
|
|
150
|
143
|
|
|
151
|
|
-* Community (Pj - project): content related with the community project, not necessarily with the outcome of the project.
|
|
152
|
|
-* Management (M): content related with the management of the roadmap, development and delivery of the outcomes of the project.
|
|
153
|
|
-* Promotion: content related with the promotion of the project in general, and the activities involved in producing the outcomes in particular.
|
|
154
|
|
-* Code and metadata: content units directly related with the code and metadata.
|
|
155
|
|
-* BuildStream description: content units related with the description of the outcomes and some specific content that helps in consumption and community support activities.
|
|
156
|
|
-* Outcomes: contents directly related with the outcomes that are "released" and/or consumed by users.
|
|
|
144
|
+* Community (Pj - project): content related with the community project, its governance and participants.
|
|
|
145
|
+* Management (M): content related with the management of the roadmap, development and delivery of the project outcomes.
|
|
|
146
|
+* Promotion: content related with the promotion of the different outcomes and activities generated by the BuildStream community.
|
|
|
147
|
+* Code and metadata: content units directly related with the code and metadata. Please be aware that some might consider the code itself as "the content".
|
|
|
148
|
+* BuildStream description: content units related with the description of the outcomes together with some additional information that helps to consume them.
|
|
|
149
|
+* Outcomes: contents directly related with the BuildStream outcomes that are "released" and/or consumed by users.
|
|
157
|
150
|
* Landing page and project page: root pages of the key/essential content with a very specific purpose.
|
|
158
|
151
|
|
|
159
|
152
|
|
|
160
|
153
|
### Content structure description
|
|
161
|
154
|
|
|
162
|
155
|
|
|
163
|
|
-Please check the diagram called BuildStream Content Structure, which is the first page of the attached .pdf file. You can also find the image in the gitlab[1]
|
|
|
156
|
+Please check the diagram[1] called BuildStream Content Structure. The following section is a description of the diagram.
|
|
164
|
157
|
|
|
165
|
158
|
|
|
166
|
159
|
#### 0. BuildStream tool landing page
|
