Skip to content

Commit e76b5fe

Browse files
alexvossalexvoss
committed
Add how we work page
1 parent e72281f commit e76b5fe

2 files changed

Lines changed: 219 additions & 0 deletions

File tree

‎docs/community/how-we-work.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
icon: lucide/pickaxe
3+
---
4+
5+
# How we work
6+
7+
We build software with and for our users, shaping strategy, design, and
8+
implementation through continuous collaboration. The aim is to ensure that our
9+
product vision and strategy are always aligned with the needs of our user
10+
community.
11+
12+
To achieve this goal, we have created a model of open development that goes
13+
beyond typical practices in Open Source and aims to create more focused and
14+
high-level discussions that drive the evolution of Zensical. We also want to
15+
make it easier for people to stay engaged with the project and contribute to it
16+
in meaningful ways. This brings a range of immediate [benefits].
17+
18+
[benefits]: #benefits
19+
20+
The key elements of our model are a [public roadmap], which outlines the
21+
trajectory of the project, and our [public backlog], which breaks down items
22+
from the roadmap into actionable and achievable tasks. We manage both in
23+
response to input from the community.
24+
25+
Our process is open to a range of contributions and we put mechanisms in place to
26+
actively curate the information we need for decision-making and development as
27+
well as to invite contributions and feedback from the user community at critical
28+
points in time.
29+
30+
[public roadmap]: https://zensical.org/about/roadmap/
31+
[public backlog]: https://github.com/zensical/backlog
32+
33+
## Change requests and the backlog
34+
35+
Change requests are an important feature of Open Source development. Of course,
36+
we invite community members to submit them via our issue tracker. We promptly
37+
integrate all change requests into a structured, transparent process.
38+
39+
Zensical is a vertically integrated set of systems that support different
40+
aspects of technical writing. It consists of a number of projects, each with its
41+
own repository and published releases. To provide a view of our development
42+
activities overall, we keep our [public backlog] separate, which we use to keep
43+
track of change requests across all projects.
44+
45+
## Process overview
46+
47+
The diagram below outlines the different stages a change request goes through
48+
and several opportunities for community members to contribute to this process.
49+
50+
```mermaid
51+
%%{init:{"themeVariables": { "noteBkgColor":"transparent", "noteTextColor":"transparent", "noteBorderColor":"transparent" } }}%%
52+
sequenceDiagram
53+
autonumber
54+
55+
actor user as Community member
56+
actor team as Team
57+
58+
participant issue_tracker as Issue tracker
59+
participant backlog as Backlog
60+
participant spark as Zensical Spark
61+
62+
user ->> issue_tracker: change request
63+
activate issue_tracker
64+
team ->> backlog: create backlog item
65+
team ->> issue_tracker: close change request
66+
activate backlog
67+
backlog -->> issue_tracker: block
68+
69+
%%note over user, team: .
70+
activate spark
71+
loop Spark
72+
user <<-->> spark: define opportunities
73+
team ->> spark: proposal
74+
team ->> spark: design document
75+
user <<-->> spark: feedback
76+
%%note over user, team: .
77+
end
78+
%%note over user, team: .
79+
80+
%%loop Public feedback
81+
team ->> backlog: release design document
82+
user -->> backlog: feedback
83+
%%note over user, team: .
84+
%%end
85+
deactivate spark
86+
87+
%%note over user, team: .
88+
loop Develop
89+
participant code as GitHub Repositories
90+
activate code
91+
team ->> code: commit
92+
user ->> code: PR
93+
%%team -->> code: review
94+
%%note over user, team: .
95+
end
96+
97+
deactivate code
98+
deactivate backlog
99+
deactivate issue_tracker
100+
101+
%% team ->> Zensical: release
102+
%%note over user, team: .
103+
```
104+
105+
## Process steps
106+
107+
1. You submit a change request on the issue tracker on one of our repositories.
108+
The issue template for change requests guides you through the submission
109+
process and ensures that we receive all the information we need to act on
110+
your change request.
111+
112+
2. We review your change request and may request further information before we
113+
create an item in our [public backlog], prioritize it and estimate its impact
114+
on the wider user base.
115+
116+
You can then subscribe to backlog items you are interested in to receive
117+
notifications of status changes. We lock backlog items until we consider
118+
the item ready for design and implementation. This keeps the notification
119+
noise to a minimum since you will only receive relevant updates. You can,
120+
of course, still subscribe to your original change request.
121+
122+
The backlog items are organized, where possible, into broader topics that
123+
match items on our [roadmap]. We will set up links between the roadmap and
124+
the backlog to allow users to navigate from either end.
125+
126+
[roadmap]: https://zensical.org/about/roadmap
127+
128+
3. We will then close your original change request to ensure that the issue tracker
129+
remains focused on currently known issues, so that you and others can always
130+
quickly investigate unexpected behavior.
131+
132+
4. We will also mark your original change request as blocked by the backlog
133+
item. This way there is a relationship that can be navigated from both ends.
134+
The backlog is a single point of reference for all repositories and is
135+
exclusively curated and managed by the Zensical team.
136+
137+
We encourage community members to always consult the backlog first as we
138+
are also regularly adding items that do not have their origin in a change
139+
request but reflect our efforts to move Zensical forward.
140+
141+
5. The separate space that [Zensical Spark] provides helps us to focus on the
142+
complex requirements and workflows of professional users. While public
143+
discussions in Open Source projects often circle around specific features and
144+
implementation details, we use this space to have higher-level discussions
145+
about the [opportunities] we need Zensical to address, on the unmet needs and
146+
pain points of people who work with it every day. We also offer private channels
147+
and NDAs to discuss confidential matters.
148+
149+
[Zensical Spark]: https://zensical.org/spark/
150+
[opportunities]: https://zensical.org/spark/methodology/#stage-1-opportunities
151+
152+
6. Once we have established a thorough understanding of the opportunity space,
153+
we will produce [proposals] for possible solutions. We explore different
154+
approaches together with our members in Zensical Spark, to ensure that all
155+
options and trade-offs have been considered.
156+
157+
[proposals]: https://zensical.org/spark/methodology/#stage-2-proposals
158+
159+
7. From the exploration proposals we distill a [design document] that provides a
160+
clear definition of the opportunities it addresses, alternative solutions
161+
that were considered, details of designs, scope, and key implementation
162+
decisions as well as identified risks and mitigation strategies.
163+
164+
[design document]: https://zensical.org/spark/methodology/#stage-3-design
165+
166+
8. We elicit feedback from members in Zensical Spark and iterate over the
167+
process as needed.
168+
169+
9. Design documents will be made available publicly before development starts,
170+
allowing users to understand upcoming changes and the rationale for them.
171+
172+
10. At this point, we invite the wider community to provide feedback on the
173+
design documents. We will incorporate feedback (as well as existing
174+
discussions on your change request) into the process as appropriate.
175+
To avoid bike-shedding, we will keep discussions within Zensical Spark.
176+
177+
11. Development happens on the public repositories of the Zensical projects. We
178+
use short-lived feature branches to ensure ongoing development and
179+
maintenance at the same time, while reducing merge conflicts to a minimum.
180+
All features will be released as Open Source.
181+
182+
12. Open Source projects thrive if their development is driven by contributions
183+
from the wider community. We invite contributors to produce pull requests
184+
after we finish the initial development phase. The established context,
185+
scope, and constraints are defined by the corresponding design document.
186+
187+
## Benefits
188+
189+
### Transparency
190+
191+
* We make our priorities transparent through the backlog, which serves as a
192+
single point of reference for the development activities in all Zensical
193+
projects.
194+
195+
* A tidy issue tracker immediately shows the currently known issues.
196+
197+
* Users can subscribe to the backlog for low-noise notifications of progress on
198+
items they are interested in.
199+
200+
### Alignment of interests
201+
202+
* By discussing opportunities, proposals, and design choices with our
203+
professional users, we ensure that we provide degrees of freedom that ensure
204+
we support both common use cases and edge cases.
205+
206+
* Design documents allow us to invite pull requests not just for bug fixes and
207+
small-scale contributions but to accept more substantial code contributions,
208+
guided by a defined context, scope, and constraints.
209+
210+
### Influence
211+
212+
* Change requests remain an important mechanism by which the community can
213+
influence the direction of an Open Source project.
214+
215+
* Discussions within Zensical Spark organized to elicit contributions from
216+
groups of users with complex requirements and workflows.
217+
218+

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,7 @@ nav:
221221
- Tooltips: authoring/tooltips.md
222222
- Community:
223223
- Get involved: community/get-involved.md
224+
- How we work: community/how-we-work.md
224225
- Contribute:
225226
- community/contribute/index.md
226227
- Bug reports: community/contribute/report-a-bug.md

0 commit comments

Comments
 (0)