Agenda
- report by learning journey WG, feedback (20 min)
- board triage (15 min)
- break down tasks (25 min)
Notes
- Number of issues is overwhelming, let’s take a look at the mid-term goals again
- We still don’t have owners/lead editors for the reference manuals, but we did find owners for the learning journey and some technical aspects
- The ones working for Season of Docs could become editorial leads
-
@asymmetric: What does a lead editor do?
-
@fricklerhandwerk: Responsible for the manual making sense, make content fit in, don’t clump together different types of documentation
-
@asymmetric: Editor can remove things, but where to move them?
-
@fricklerhandwerk: Editor can focus on e.g. just the Python section, analyze and decide where to move parts. How to organize it and present it well
-
@asymmetric: Editor can’t do stuff well themselves, a lot of interconnected things, where to start? May that be the learning journey working group’s reponsibility instead?
-
@fricklerhandwerk: We’re trying to untangle it and establish a plan.
-
@infinisil: Can break it down by saying the lead editor for e.g. Python section should subscribe to updates, ensure it doesn’t get worse or improve it
-
@asymmetric: I’d be up to that for a subsection of the manual, maybe Rust
- do I need to be a domain expert?
-
@fricklerhandwerk: Don’t need to be an expert, can be very straightforward to do; team can help find experts to ask
-
@asymmetric: For nix-doc, spent a lot of time to understand things, whereas people with knowledge could’ve done it a lot faster, who to talk to to get info about things, should we have a process for that?
-
@fricklerhandwerk: Can’t be perfect, there will always be abandonware. Is the goal of the team
-
@asymmetric: Would like to be able to say “I need help with X” and be guided to the right people
-
@fricklerhandwerk: Can ping people that touched the code before, but they might not respond.
- There is a lot of implicit knowledge around, distributed over many people who evolve or distribute it.
- When finding these people, one can either learn the knowledge, or write it down for others to learn.
- Lazy rabbitholing: When finding a rabbit hole, write down the problem for others to find before jumping into it.
- Concretely: Open an issue or make a draft, ask people to contribute
-
@infinisil: to find the right people, do the usual things:
- check the commit log,
CODEOWNERS, …
- ask around on the relevant chatrooms
- eventually people who are involved will pop up
-
@fricklerhandwerk: that information should be available in the right place, currently we still need people to answer that over and over
-
@asymmetric: Not trying to fix a problem of my own, but rather the manual. Maybe one could escalate this somehow?
-
@fricklerhandwerk: Write it down how we can find the right people. Can be a couple-hours task:
- Write it down
- Decide where should it be put
- Get and process reviews from those involved and knowledgeable
- Team is there to break down tasks and define leaf tasks.
-
@asymmetric: what if we had a room on Matrix where one can ask who to ask?
-
@fricklerhandwerk: unless we have a chatbot, that doesn’t scale
- we have some people who do this for parts of user/contributor issues on Discourse already
- it will be a high-traffic channel, very noisy
- someone has to take care of this consistently
- would be great to have a community team for that, but out of scope here
- (collaboratively drafted a piece of contributor guidance)
-
@fricklerhandwerk: This is what we should in this team, hopefully we can scale it up to more broken-down issues per meeting in the future
-
@infinisil: Could make it a goal to always have a constant number of written-down tasks for people to start, e.g. 10 of them
Hosted by Flying Circus.