Hi,
during Guix Days we spent most of the time discussing different topics
in different breakout rooms. I'm attaching the ones I took at the
"Community processes optimizations and documentation" room (I probably
missed something, so feel free to edit these). I know some of the notes
have been lost and later recovered so if anyone else has notes to share
please attach them in this thread.
Thank you all for the awesome time we had,
cheers,
giacomo
# Community processes optimizations and documentation
We have a very inviting and welcoming culture and great documentation
- we could better define how people could get involved
- figure out what are the rough edges for newcomers both as contributors and users
- a reorganization of the documentation could be useful
## Teams
- for example we could explain more clearly what do we expect from teams and team members. should they commit to be connected to IRC? should they commit to read the mailing list?
- there is a manual section for teams but there is no general overview of how the Guix project is structured and an explaination of its roles: team member, committer, maintainer and so on and so forth
- we have documentation very much focused on hacking but a sane project needs much more
- teams should feel empowered and responsible to handle management tasks such as keeping the list of members (for example dropping inactive members). intra-team processes should be defined by the team. They should also be responsible to document how they work and their internal processes
- to have the expectations described above met, we could ask for all committers be part of a team
- also should committers be forced to be subscribed to the guix-devel mailing list? or another one? the problem is twofold:
+ communications with teams
+ a more forum like experience (maybe Zulip or similar tools). Should we move help-guix to another platform? there are mixed experiences on this topic.
+ people are looking for help for Guix in many different places. it would be useful to have a central place where everyone feels heard and seen. fragmentation is a natural phenomenon, but it should happen by choice not need. we could look into having a list of unofficial communication
### Teams and communications
- how can the release team inform team members that they have to prepare for a release?
- there need to be a role/process/tool that makes sure that the information spreads
+ it seems logical to use Codeberg to do so
+ otherwise a mailing list for team members (for the whole project or for single teams, to be decided)
- it would be helpful to have a platform which better supports search compared to email archives (web search is not very good and requires newcomers to download the email archive and run a local index, which is a high bar)
- in general there is a lot of ways for this to be implemented. it seems a common need for all proposition is to have a list of teams, with their canonical name, Codeberg handle, canonical communication channel and link to the documentation of the team's workflow
- the teams.scm file is the source of truth , we could add the necessary information to it and generate HTML from it
- there is a tension between different needs and expectations from communication media. we could explore more the Codeberg API to figure out whether we can leverage it to communicate with teams. in general there seems to be a preference to, in the end, receive an email for many people. Zulip has also been mentioned, it has a lot of features and can be integrated with IRC.
### Teams documentation
- the manual section states the scope and responsibilities for teams member
- but many people may not find that section in the manual as it's not really a reference information for the software
- the documentation team could use help, join it if you find it interesting!
