GNOME.org
 

[Notes] [Git][BuildStream/nosoftware/alignment][toscalix] 6 commits: Made a small correction on the structure. This is a commit to evaluate the…

Title: GitLab

Agustin Benito Bethencourt pushed to branch toscalix at BuildStream / nosoftware / alignment

Commits:

8 changed files:

Changes:

  • .directory
    1 
    +[Dolphin]
    2 
    +Timestamp=2018,5,17,17,48,0
    3 
    +Version=4
    4 
    +ViewMode=1
    5 
    +VisibleRoles=Details_text,Details_size,Details_modificationtime,Details_permissions,CustomizedDetails
    6 
    +
    7 
    +[Settings]
    8 
    +HiddenFilesShown=true

  • BuildStream_policies.md
    ... ... @@ -83,11 +83,11 @@ Check the templates used at BuildStream:
    83 83 
         * bug template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/bug.md
    84 84 
         * Merge request template: https://gitlab.com/BuildStream/buildstream/blob/master/.gitlab/merge_request_templates/bst_merge_request.md
    85 85
    86 
    -## Technical/engineering tasks: best practices.
    86 
    +### Technical/engineering tasks: best practices.
    87 87
    88 88 
     These are the best practices that are applied to Gitlab at BuildStream in relation with bugs and tasks. Please read them carefully and try to apply them.
    89 89
    90 
    -### Open/create a technical issue
    90 
    +#### Open/create a technical issue
    91 91
    92 92 
     In order to open a new task the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
    93 93 
     * Use the default template.
    ... ... @@ -108,7 +108,7 @@ In order to open a new task the best place is the green button at this page: <ht
    108 108 
     		* The MR associated with the ticket. Please do not forget this.
    109 109 
     	* If your issue remains unprocessed after a few days/weeks, please ask through the project mailing list about it. It should be the exception but it might have been overlooked or remain unnoticed.
    110 110
    111 
    -### Update an engineering task / ticket
    111 
    +#### Update an engineering task / ticket
    112 112
    113 113 
     Assuming the bulk of the work on engineering tasks takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
    114 114 
     * Assign the ticket to you when you start working on it. More than one person can be assigned to a single task.
    ... ... @@ -118,13 +118,13 @@ Assuming the bulk of the work on engineering tasks takes places on Merge Request
    118 118 
     * Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
    119 119 
         * This is very important for others to follow up your work.
    120 120
    121 
    -### Close an engineering task
    121 
    +#### Close an engineering task
    122 122
    123 123 
     (coming soon)
    124 124
    125 
    -## Bugs: best practices
    125 
    +### Bugs: best practices
    126 126
    127 
    -### Open/create a bug
    127 
    +#### Open/create a bug
    128 128
    129 129 
     In order to open a new bug the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
    130 130 
     * Use the Bug template. Choose it from the template menu when creating a new bug.
    ... ... @@ -141,7 +141,7 @@ In order to open a new bug the best place is the green button at this page: <htt
    141 141 
     * Further considerations:
    142 142 
     	* Please refer to the considerations made for issues since they also apply to this case.
    143 143
    144 
    -### Update a bug
    144 
    +#### Update a bug
    145 145
    146 146 
     Assuming the bulk of the work on bugs takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
    147 147 
     * Assign the bug to you. More than one person can be assigned to a single bug.
    ... ... @@ -155,13 +155,13 @@ Assuming the bulk of the work on bugs takes places on Merge Requests (code), it
    155 155
    156 156 
     These are the different policies that the project applies to merge requests.
    157 157
    158 
    -### Close a Bug
    158 
    +#### Close a Bug
    159 159
    160 160 
     (coming soon)
    161 161
    162 
    -## Merge requests (MR): best practices
    162 
    +### Merge requests (MR): best practices
    163 163
    164 
    -### Open/create a merge request
    164 
    +#### Open/create a merge request
    165 165
    166 166 
     Please read carefully the following policies before opening a new merge request. The best place to create a new merge request is this page: <https://gitlab.com/BuildStream/buildstream/merge_requests>. Please follow these considerations:
    167 167 
     * Use the default template.
    ... ... @@ -177,7 +177,7 @@ Please read carefully the following policies before opening a new merge request.
    177 177 
     	* If you want to notify somebody about the merge request, please add his/her name as first comment, starting by the character "@". Try to avoid naming people for notification reasons in the merge request  description field.
    178 178 
     	* If your merge request remains unprocessed for over a week, please ask through IRC (#buildstream in irc.gonme.org) about it. It should be the exception but it might have been overlooked, remain unnoticed or the default reviewer is overloaded.
    179 179
    180 
    -### Update a merge request
    180 
    +#### Update a merge request
    181 181
    182 182 
     It is strongly recommended that you follow these advices:
    183 183 
     * Assign the Merge Request to you when you start working on it. Please remember than more than one person can be assigned to the MR.
    ... ... @@ -185,6 +185,12 @@ It is strongly recommended that you follow these advices:
    185 185 
        * If the MR is in progress, please assign to it the label "Doing", removing the "ToDo" label if present.
    186 186 
        * every MR should be related in the description field to at least one engineering task or bug. Please check this is the case.
    187 187 
     * Update the MR when a relevant event takes place.
    188 
    +
    189 
    +#### Close a Merge Request
    190 
    +
    191 
    +(coming soon)
    192 
    +
    193 
    +## Roadmap policies
    188 194
    189 195 
     ## Suggest improvements or additions to the BuildStream policy
    190 196
    ... ... @@ -194,6 +200,3 @@ If the suggestion refers to how to manage tickets, bugs or merge requests or any
    194 200
    195 201 
     You can always send the proposal to the <mailto:buildstream-list gnome org> mailing list if any of the options above fits or you are unsure about what to do.
    196 202
    197 
    -### Close a Merge Request
    198 
    -
    199 
    -(coming soon)

  • content_design/.directory
    1 
    +[Dolphin]
    2 
    +HeaderColumnWidths=603,80,134,101
    3 
    +Timestamp=2018,8,8,11,49,49
    4 
    +Version=4
    5 
    +ViewMode=1
    6 
    +VisibleRoles=Details_text,Details_size,Details_modificationtime,Details_permissions,CustomizedDetails

  • content_design/BuildStream_Content_Structure_all.pdf
    No preview for this file type
  • content_design/BuildStream_Content_Structure_critical_path.pdf
    No preview for this file type
  • content_design/BuildStream_Content_Structure_critical_path_per_target.pdf
    No preview for this file type
  • content_design/BuildStream_Content_Structure_diagram.pdf
    No preview for this file type
  • content_design/content_structure_proposal_description.md
    1 
    +## Content Structure Full Proposal
    2 
    +
    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 
    +
    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.
    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].
    8 
    +
    9 
    +### Content Units
    10 
    +
    11 
    +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 
    +
    13 
    +For example:
    14 
    +
    15 
    +* Wikis allow to embed the content of a page in another page.
    16 
    +* Two content units can be published initially in a single web page and, when they expand, separated into two.
    17 
    +
    18 
    +
    19 
    +I will refer to pages or files only  in specific cases.
    20 
    +
    21 
    +### Target audience
    22 
    +
    23 
    +Based on the BuildStream target audience, I propose, for simplicity to consider the following target audience when it comes to content design:
    24 
    +
    25 
    +* Those unaware of the existence of BuildStream (99%)
    26 
    +* Those aware of the existence of BuildStream (1%)
    27 
    +	* BuildStream users (0.1%)
    28 
    +		* BuildStream contributors (0.01%)
    29 
    +
    30 
    +
    31 
    +In general, when I refer to users, I will also be referring to contributors.
    32 
    +
    33 
    +As the project, so the content, matures, it would be ideal to segment some of the above target audiences.
    34 
    +
    35 
    +Occasionally, the proposal or/and content itself might refer to the following subgroups:
    36 
    +
    37 
    +* Users
    38 
    +	* Integrators: those who use BuildStream as part of the delivery process (integration stage).
    39 
    +	* Developers: those who use BuildStream as part of their development process.
    40 
    +* Contributors
    41 
    +	* Core contributors: those who contribute on regular basis, normally to specific/key areas.
    42 
    +	* Occasional, sporadic, opportunistic contributors: the rest of the contributors.
    43 
    +
    44 
    +
    45 
    +This might provide a hint on further target audience segmentation we can define in the coming future.
    46 
    +
    47 
    +### Tools
    48 
    +
    49 
    +Initially we will work with what we have:
    50 
    +
    51 
    +* The GNOME wiki
    52 
    +* Gitlab:
    53 
    +	* The current guide.
    54 
    +	* Key files in repos (specially buildstream.
    55 
    +
    56 
    +
    57 
    +The structure is designed to be as "tool agnostic" as possible.
    58 
    +
    59 
    +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.
    60 
    +
    61 
    +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.
    62 
    +
    63 
    +### Timeline
    64 
    +
    65 
    +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.
    66 
    +
    67 
    +### Content management
    68 
    +
    69 
    +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.
    70 
    +
    71 
    +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.
    72 
    +
    73 
    +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.
    74 
    +
    75 
    +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.
    76 
    +
    77 
    +### Criteria followed to structure the content units
    78 
    +
    79 
    +Assuming the Open Source nature of the project and the fact that we are developing an integration tool for a pre-defined target audience, the following criteria has been followed to structure the proposed content units:
    80 
    +
    81 
    +
    82 
    +#### Expected content change rate
    83 
    +
    84 
    +
    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 appropriate for each unit too.
    86 
    +
    87 
    +For simplicity, I have considered the following groups:
    88 
    +
    89 
    +* (almost) Static: content that is not expected to change frequently, i.e. project principles or Manifest.
    90 
    +* Dynamic: content that is expected to change frequently, grow overtime or have a limited life expectancy.
    91 
    +* Replaceable: due to the nature of our activity, there is a specific subset of content that will be replaced by new content when a specific event occurs, mostly releases. Do no mistake replaceable with erasable. In theory, these contents will not be erased but new content will play its role.
    92 
    +* Erasable: temporary pages that will die for exceptional reasons, like the usage of a new tool.
    93 
    +
    94 
    +
    95 
    +#### Front page vs project and landing pages
    96 
    +
    97 
    +
    98 
    +There are two main content units we will used as "root units" in terms of the proposed content structure:
    99 
    +
    100 
    +* Project page.
    101 
    +* Landing page.
    102 
    +
    103 
    +
    104 
    +I refer to them as pages, instead of units, because they are single pages and also because is a very common terminology.
    105 
    +
    106 
    +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).
    107 
    +
    108 
    +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.
    109 
    +
    110 
    +
    111 
    +#### Outcomes as the most influential event
    112 
    +
    113 
    +
    114 
    +Assuming the normal journey to become a maintainer:
    115 
    +
    116 
    +Humanity -> User -> Power user -> Occasional Contributor -> Core contributor -> Maintainer
    117 
    +
    118 
    +at this point of maturity of the project, releases allow us to maximize the impact of our efforts to gain users while, at the same time, it help us internally to synchronize the efforts of contributors and power users with different goals and expectations.
    119 
    +
    120 
    +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.
    121 
    +
    122 
    +In my experience, using the concept of releases as criteria for defining the content structure of projects that:
    123 
    +
    124 
    +* Need the kind of attention that leads them to find users with technical profile.
    125 
    +* Does not have a meaningful number of experienced technical product content creators.
    126 
    +* Cannot or do not want to heavily invest in promotion/marketing activities compared to development ones.
    127 
    +
    128 
    +
    129 
    +.... work well.
    130 
    +
    131 
    +
    132 
    +#### Use cases and sister projects
    133 
    +
    134 
    +
    135 
    +BuildGrid has been considered as a "sister project". Initially, it can rely of the current structure to minimize the effort required from their side.
    136 
    +
    137 
    +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.
    138 
    +
    139 
    +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.
    140 
    +
    141 
    +### Topic
    142 
    +
    143 
    +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].
    144 
    +
    145 
    +The topics are:
    146 
    +
    147 
    +* Community (Pj - project): content related with the community project, not necessarily with the outcome of the project.
    148 
    +* Management  (M): content related with the management of the roadmap, development and delivery of the outcomes of the project.
    149 
    +* Promotion: content related with the promotion of the project in general, and the activities involved in producing the outcomes in particular.
    150 
    +* Code and metadata: content units directly related with the code and metadata.
    151 
    +* BuildStream description: content  units related with the description of the outcomes and some  specific content that helps  in consumption and community support activities.
    152 
    +* Outcomes: contents directly related with the outcomes that are "released" and/or consumed by users.
    153 
    +* Landing page and project page: root pages of the key/essential content with a very specific purpose.
    154 
    +
    155 
    +
    156 
    +### Content structure description
    157 
    +
    158 
    +
    159 
    +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]
    160 
    +
    161 
    +
    162 
    +#### 0. BuildStream tool landing page
    163 
    +
    164 
    +
    165 
    +This would be the starting point for those looking for a general definition of what BuildStream is and what is for. It is meant to be a static page.
    166 
    +
    167 
    +
    168 
    +#### 1. BuildStream project page
    169 
    +
    170 
    +
    171 
    +This would be the starting/root point for those contents related with the BuildStream Open Source project.
    172 
    +
    173 
    +
    174 
    +#### C. BuildStream Code ==
    175 
    +
    176 
    +
    177 
    +There is a well documented by now change in behavior when it comes to content consumption related with Open Source projects that favors for certain profiles specific repo files over content in other platforms, specially when the information is tightly related with the code.
    178 
    +
    179 
    +For complex and bigger project this trend represents a challenge since involves content maintenance related risks (inconsistency, duplication, outdated info...), specially when other content platforms are not git based, like in our case, where the GNOME wiki pages are editable.
    180 
    +
    181 
    +In terms of design, we will need to consider the following, to mitigate such risks:
    182 
    +
    183 
    +* README files will be nothing but a summary of what is present in other pages. Links to those pages will be included in the README file and will need to be maintained.
    184 
    +* BuildStream will have the README file of the master branch as the entry point for contributors, instead of Master (outcome) unit initially. As the tool grows and becomes more mature, this decision might change.
    185 
    +* The following relations need to be consider in order to avoid some of the mentioned risks:
    186 
    +	* C.2 README.rst - R.2 Master, 0. Landing Page, R.3 Feature Page and R.4 Deployment Howto units.
    187 
    +	* C.3 LICENSE file - Pj.2 Governance+license+sponsors content units.
    188 
    +	* C.4 News/Release notes file - R.3 Feature page and D. BuildStream In Detail content units.
    189 
    +	* C.5 Maintainers - Pj.5 Community support and Tools content unit.
    190 
    +
    191 
    +
    192 
    +C.1 BuildStream download page
    193 
    +
    194 
    +The Download page is the central reference not just to download the outcomes delivered by the project, but also the associated metadata. It will also have structured and direct references to all the information required to have a smooth deployment/installation experience.
    195 
    +
    196 
    +The structure of this unit will consider:
    197 
    +
    198 
    +* Versioning.
    199 
    +* Platforms where BuildStream is expected to be installed.
    200 
    +* Deployment mechanisms/technologies.
    201 
    +* Complementary plugins and tools required for the deployment/installation/usage of BuildStream.
    202 
    +* Additional content units that any user needs  to consider.
    203 
    +* Critical path design to ensure that the journey through BuildStream contents takes place in the pre-established order. This consideration applies in fact to, at least, every unit that is part of the critical path of any considered target audience.
    204 
    +
    205 
    +
    206 
    +C.2 Release branch and master README file
    207 
    +
    208 
    +Short, to the point, description of what is BuildStream for and how to consume it, together with links to further information, adding context to each one of them. That additional or complementary information could be (related with):
    209 
    +
    210 
    +* Documentation - D. BuildStream in detail unit
    211 
    +* Community support (get help) - D.5 FAQ.
    212 
    +* Contributing - Pj.3 How to contribute unit.
    213 
    +* Licensing and copyrights - C.3 LICENSE and Pj.2 Governance+license+sponsors
    214 
    +
    215 
    +
    216 
    +Relations: C.2 README.rst - R.2 Master, 0. Landing Page, R.3 Feature Page and R.4 Deployment Howto units.
    217 
    +
    218 
    +C.3 Release branch and master Copying/LICENSE file
    219 
    +
    220 
    +This unit should include:
    221 
    +
    222 
    +* Project license. Explicit description. Links.
    223 
    +* Exceptions (if any) that are included in the repo. Explicit description. Links.
    224 
    +
    225 
    +
    226 
    +Relations: C.3 LICENSE file - Pj.2 Governance+license+sponsors content units. A complementary proposal related with compliance will be sent.
    227 
    +
    228 
    +C.4 Release branch and Master (dev releases) NEWS/Release Notes.
    229 
    +
    230 
    +News related with each release (digested release notes). Further content can be considered in this unit or separate ones like:
    231 
    +
    232 
    +* Changelog
    233 
    +* Raw release notes.
    234 
    +
    235 
    +Relations: C.4 News/Release notes file - R.3 Feature page and D. BuildStream In Detail content units.
    236 
    +
    237 
    +C.5 Release branch and master Maintainers file
    238 
    +
    239 
    +List of maintainers, responsibility and contact.
    240 
    +
    241 
    +Relations: C.5 Maintainers - Pj.5 Community support and Tools content unit.
    242 
    +
    243 
    +
    244 
    +#### Pr. BuildStream Promotion
    245 
    +
    246 
    +
    247 
    +Content units related with promoting BuildStream among the key targets including the promotion of the different releases, talks, finished features, etc. .
    248 
    +
    249 
    +Pr.1 BuildStream Out There
    250 
    +
    251 
    +This content unit collects the main references and contents about BuildStream that has been published by media or community members. It will also contain the data about the impact of the tool. Overtime, this unit becomes an important resource for a variety of decisions.
    252 
    +
    253 
    +Pr.2 Social media campaign
    254 
    +
    255 
    +Place to build social media campaigns, specially during the release of BuildStream. It also defines who and how the project is being promoted through social media.
    256 
    +
    257 
    +Pr.3 News / Announcements
    258 
    +
    259 
    +Announcements generated by the project, like release announcements. News to be consumed by community Members or supporters would be also a matter of this section/pages.
    260 
    +
    261 
    +Pr.4 Blog
    262 
    +
    263 
    +Project blog where contributors talk about what they have done/contributed.
    264 
    +
    265 
    +
    266 
    +#### M. BuildStream Management
    267 
    +
    268 
    +
    269 
    +Set of pages dealing with the management of the different aspects of the creation, release and maintenance of BuildStream toolset.
    270 
    +
    271 
    +
    272 
    +M.1 BuildStream roadmap
    273 
    +
    274 
    +Roadmap description including the different release timelines.
    275 
    +
    276 
    +M.2 BuildStream release howto
    277 
    +
    278 
    +This content unit describes the management aspects of the release process.
    279 
    +
    280 
    +M.3 BuildStream development policies/guides
    281 
    +
    282 
    +Policies and guides that BuildStream developers should follow in order to get their code accepted, including unit tests and documentation.
    283 
    +
    284 
    +M.4 BuildStream delivery and operations policies/guides
    285 
    +
    286 
    +Set of guides and policies followed by those involved in delivery and operations tasks at BuildStream project, including information related with those managing the different services affecting the development, delivery and release.
    287 
    +
    288 
    +
    289 
    +#### BuildStream in Detail
    290 
    +
    291 
    +
    292 
    +This would be the content describing in detail the tool, including the features, components, dependencies and other elements. The ideal situation would be to have a page that provides an overall context of all the features, called BuildStream in Detail, and then links to more detailed information about each feature or component. It is important to provide a clear relation between problem statement/use case and feature.
    293 
    +
    294 
    +It is important to translate to the content the architecture of the tool when it comes to core vs complementary features if, like in our case, they are developed/managed slightly different, so the feature and associated content maintenance expectations are set correctly.
    295 
    +
    296 
    +It is important to link the feature descriptions to code, so the content is worth for a wide range of profiles, making the published content valuable in a wider range of situations.
    297 
    +
    298 
    +
    299 
    +D.1 Integrate with BuildStream: examples
    300 
    +
    301 
    +Examples of how to use the tool. The content can be created and maintained by the project itself and or referenced from work done outside the project. AS in other cases, it should be a clear difference between what is expected to be maintained by the project participants and what is "external". This is relevant when requesting/providing support to users and when managing negative feedback on internet.
    302 
    +
    303 
    +
    304 
    +D.2 BuildStream plug-ins and other complementary features
    305 
    +
    306 
    +The complementary features, like plugins, should be documented and it is this page the starting point. It is expected that some of this features will be developed outside the project so it is necessary to structure the content in a way that a user or contributor can identify what to expect from the project in terms of maintenance or/and community support.
    307 
    +
    308 
    +
    309 
    +D.3 BuildStream core features description
    310 
    +
    311 
    +Detailed description of the core features shipped by BuildStream, including those who are new on each release. Ideally, this content will provide links to additional complementary documentation that would help readers to understand the use cases behind the features, the features description themselves and how to consume them.
    312 
    +
    313 
    +
    314 
    +D.4 BuildStream glossary
    315 
    +
    316 
    +Each project uses specific terminology that requires explanation. In regulated or safety critical environments or in Open Ocean, this need becomes almost a requirement. The same principle applies to mature markets when using terminology as a differentiation element.
    317 
    +
    318 
    +BuildStream will have a glossary.
    319 
    +
    320 
    +
    321 
    +D.5 BuildStream FAQ
    322 
    +
    323 
    +The FAQ is a relevant content element, often just appreciated by projects that has reached a mature state. BuildStream FAQ is proposed to become a key step in the critical path designed for two different target audiences at two different points in the "content journey", which means that this FAQ should be structured accordingly.
    324 
    +
    325 
    +
    326 
    +#### BuildStream outcomes (portfolio)
    327 
    +
    328 
    +
    329 
    +Contents related with the different "products" offered by the BuildStream project. Each outcome should have a separated content page. So far, we have three different outcomes:
    330 
    +
    331 
    +* Even releases: targeting users
    332 
    +* Odd releases: targeting testers (users and contributors)
    333 
    +* Master: targeting contributors
    334 
    +
    335 
    +
    336 
    +R.1 BuildStream releases: portfolio charter
    337 
    +
    338 
    +This page will have links to all the BuildStream releases, highlighting the current one, the ones maintained or recommended for the different profiles, together with the links to the complementary information that might be related to releases, like roadmap, announcements, etc.
    339 
    +
    340 
    +
    341 
    +R.2 Master
    342 
    +
    343 
    +Master as such is not released but in BuildStream portfolio, it is the default outcome for contributors. As such, this page would be the default to route first time contributors as well as occasional contributors that requires information about changes in policies and other topics that might affect Master.
    344 
    +
    345 
    +
    346 
    +R.3 BuildStream releases feature page
    347 
    +
    348 
    +The feature page is the central page for each release, that contains the information about what is released, compared with previous releases. It also includes all the necessary links to have a wide view of how to evaluate consume and get community support for a specific release.
    349 
    +
    350 
    +
    351 
    +R.4 BuildStream deployment howto
    352 
    +
    353 
    +Each release will have instructions on how to install/deploy BuildStream for the various platforms available. Part of this information would be created and maintained by the project itself and part will be available in other sites, external to the project. This page will ensure the information is available to those BuildStream users and contributors who intend to consume BuildStream.
    354 
    +
    355 
    +
    356 
    +R.5 Known issues
    357 
    +
    358 
    +On every release, there are problems that has been identified by those working on the project and not yet resolved. In some cases, there are workarounds available. This page will include such information, specially valuable prior or immediately after a release. This content should provide context/summary of what is already available on the ticketing system.
    359 
    +
    360 
    +
    361 
    +### Pj. BuildStream Project
    362 
    +
    363 
    +
    364 
    +Contents related with the BuildStream Open Source project.
    365 
    +
    366 
    +Pj.1 Project Manifest (principles) , Mission and target audience definition
    367 
    +
    368 
    +Page describing the principles that drive the BuildStream community, its mission and the target audience in both, users and contributors.
    369 
    +
    370 
    +
    371 
    +Pj.2 Governance + license + sponsors
    372 
    +
    373 
    +This page includes the governance aspects of the project, including the licenses and the project sponsors, as well as the relation with GNOME.
    374 
    +
    375 
    +
    376 
    +Pj.3 How to participate
    377 
    +
    378 
    +This page includes the information required to participate in the project including the basic communication channels and links to read as initial steps.
    379 
    +
    380 
    +
    381 
    +Pj.4 Meetings and events
    382 
    +
    383 
    +This page includes the events in which the BuildStream project participates and organizes. It should include also a list of the regular meetings, how to participate and where to find the logs.
    384 
    +
    385 
    +
    386 
    +Pj.5 Community support and tools
    387 
    +
    388 
    +Description of the tools used by the BuildStream community, how to get access and description of the communication channels listed. This page complements Pj.3 since this page targets existing contributors instead of new ones.
    389 
    +
    390 
    +### Critical paths
    391 
    +
    392 
    +One day BuildStream will dominate the world. We will be able  to look at behavioral flows on our site and see how people consume our contents and download/update our tool set just as the best retail company does. That would mean that we not just understand what our users and contributors want from us, but that we can anticipate what they might want from us tomorrow.
    393 
    +
    394 
    +To get there, we need to start today, simple but start.
    395 
    +
    396 
    +Having already defined our target audience to some extend was the first step. The content structure was the second one. The third one is to define our content considering a critical path, which is the journey we want to take our users through in order to consume our outcomes having a satisfactory experience. In other words, maximizing our conversion rate.
    397 
    +
    398 
    +In order to start simple, we will segment our audience in four groups, defining a critical path for each one of them. The target audiences are:
    399 
    +* People unaware of BuildStream
    400 
    +* People aware of BuildStream
    401 
    +* BuildStream user
    402 
    +* BuildStream contributor
    403 
    +
    404 
    +The two diagrams explain those critical paths:
    405 
    +* The diagram "BuildStream_Content_Structure_critical_path_per_target.pdf"[2] defines the critical path per target audience group.
    406 
    +* The diagram "BuildStream_Content_Structure_critical_path.pdf"[3] defines the critical path as a workflow.
    407 
    +
    408 
    +Each content unit  is related with the one described in the content structure. Once we consolidate these critical paths, we will evaluate them and improve them. We will also add new ones once we have revisited our current target audience structure, lowering the granularity of our segmentation.
    409 
    +
    410 
    +### Evaluation of the conversion rate: metrics
    411 
    +
    412 
    +We will need to answer to following questions: are the BuildStream content helping to move people away from the Unaware group into the contributors segment group?
    413 
    +
    414 
    +Which means that we need a way to evaluate if the content structure, the content themselves and the critical paths work as expected. There are tools that provide metrics and dashboards to analyze the potential answers to these questions. Before we get to this point, we can evaluate the following:
    415 
    +* Number of downloads of BuildStream..
    416 
    +* Number of regular updates of BuildStream.
    417 
    +* Hits per page.
    418 
    +* Permanence time per page.
    419 
    +* Source of the hit (search engine, social media, another BuildStream page...)
    420 
    +
    421 
    +which will provide us enough information to start learning about how well are we doing in terms of designing the contents the different target audiences need. Obviously the above information will only provide us trends in a blur picture, but overtime that is a good base to improve.
    422 
    +
    423 
    +
    424 
    +## Further resources
    425 
    +
    426 
    +The following resources are recommended:
    427 
    +[1] BuildStream_Content_Structure_diagram.pdf:
    428 
    +[2] BuildStream_Content_Structure_critical_path_per_target.pdf:
    429 
    +[3] BuildStream_Content_Structure_critical_path.pdf:
    430 
    +[4] BuildStream_Content_Structure_all.pdf:

    • —
    View it on GitLab.
    You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.

    [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]