Docs team charter proposal

Okay, I’ve written a draft team charter, with some inspiration from (and occasional plagiarism of) the Workstation Working Group.

I don’t expect that this is the final form, but it’s a lot easier to work with something than nothing, so here we go.

A few notes on why I did or did not include certain things, outstanding questions, etc:

  • I chose the “core member”, “member”, and “contributor” as the names for the membership levels to keep them generic. I thought about “editor”, “writer”, and “contributor” but rejected those because 1. I felt like they implied that editors don’t write and writers can’t edit. 2. it ignores the technical/tooling contributions
  • I made the membership period open-ended for simplicity, but included a process for removing folks who are inactive. The same process is used to remove someone who consistently makes bad contributions or is hostile to other team members.
  • There’s not a lot of difference between core member and member, except in terms of repo permissions. I think that’s okay, but maybe we need to make core member seem more appealing?
  • I intentionally left the contribution requirements for core member and member vague because trying to codify them seems like an exercise in edge case creation. This is in line with the Provenpackager policy
  • I chose to not have an elected leader because most of what that person would do is chair meetings and that’s just as easily done by getting a volunteer to run the meeting on a week-by-week basis. However, there’s something to be said for having a team lead role, so if we were to add it, I’d suggest it be elected after each release and set core member status as a requirement.
  • I avoided setting specific vote requirements wherever possible because we don’t have a fixed number of people the way, e.g. FESCo does. FESCo can have a well-defined voting policy because they have a well-defined membership count and period.

I think the general major issue remains the “entry barrier” to contribution. But making it more attractive to take the efforts to get involved in the Docs because of some reward sounds interesting.

Maybe that are little tasks but, imho, it is already a type of chair what we have, even if it is not a critical full-time job. But he/she keeps the “Docs team” together, summarizing/collecting an agenda and then leading through it in the meetings. The coordination effort value should not be underestimated. Imho, currently the Docs’ “agency” is centered around the Co-chairmanship of you and @pboy . So why not formalize and reward that (which increases attractiveness), even if the job of the chair/leader is just defined by these “little” tasks. Because these are neither invasive nor critical tasks, an election might be simplified, in discussion.fp or so, to keep it KISS.

This could also be a job to work towards, and since no damage can be done in the short term that the others couldn’t compensate for, a more regular change of leader wouldn’t be problematic either… so in terms of increasing attractiveness and a type of reward for being in the Docs

I’m not sure it does increase attractiveness, as it turns an occasional activity into a weekly obligation. Having a defined team lead makes role seem bigger than it is. “I can run a meeting once a month” is much less of a commitment than “I will run meetings for the next six months”. I’d also be concerned about people saying “well, I’m not the team lead so I don’t want to step on anyone’s toes” and not doing work that they absolutely could be doing.

The team lead title is a nice reward for those who want it, but in my mind that doesn’t outweigh the sustainability and cooperativeness of a rotating chair model.

1 Like

My idea was more to combine both. Rotating in a shorter cycle. Given the reasons we already pointed out, I do not see the need to establish a 6 month leader continuity. I think there is much possibility in between long term leadership commitment and no leader at all. The point is that someone can say: hey, I have taken that responsibility (some times). Even if we change it monthly. But there are other ways of being attractive as well of course :wink:

If I try to think of a persona who comes to the Docs,

  • A complete beginner who comes to the user documentation to find installation guide, and wants to be a contributor without having exact skill set, but is a keen writer in technical domain or instructional manual/user docs/web publishing,
  • An experienced user who wants to get a reminder of how to install a different Fedora Linux edition or spin, and is curious of technical writing workflow in the Fedora Docs and improving existing content or suggesting new content,

My imagination for such persona is limited, but this is as far as I can think of.
The entry barrier to contribution for persona I described may be already low.

I’m sure contributor documentation can pique their interest in technical writing.

I don’t disagree, but that’s off-topic for this thread. We’re discussing the team charter here.

Edit to add: this is about how we govern ourselves over the long term, not about how we recruit new contributors. Yes, they are somewhat related, but we can’t “boil the ocean” if we want to make progress.

I meant a different type of entry barrier (the need to invest much time especially at the beginning even for little tasks, compared to other Docs), but as @bcotton said, let’s postpone that topic to focus the charter here.

1 Like

I agree with the entry barrier and it actually is directly mentioned in the charter.

It states that contributors needs to submit documentation changes via “merge requests or patches”. IMO, that is a significant barrier to contribution and will lessen the amount of contributors who are willing to contribute and, as a result, lower the quality of the documentation.

Sure, I went off on a tangent about the team charter.
In governance perspective, the membership levels and attainment make sense to me.

Accepted, although my perception is the other way around. The terms in my perception are too exclusive based on personal characteristics (“member”) instead of tasks and scope of work explicitly committed to. And we could have Editors and Administrators, Writers/Authors and WEB developers, etc.

I don’t know. We need a group of people who will regularly attend meetings, reliably take on and complete tasks, respond to mails in a reasonable amount of time, and speak up in discussions here. Is that “appealing”? * In a special way, maybe.

We don’t need a leader, but maybe something like a secretary or coordinator. (Nearly) all the Edition working groups have it, either by appointment or because it happened that way somehow. The week-by-week model works only for a small group with a limited variety of topics. And chair meeting is the minor part. You need an overview of all the various topics, summarize the various statui achieved, organize a stringent discussion, etc.

Christopher Kloozpy0xc3 view seems to me more realistic and practical (apart from about my role).

I like that, in theory. But week-by-week may be a bit too spontaneous for long-running topics. Probably it works on a monthly or quarterly base, or on a milestone base.

But the proof of the pudding is in the eating (or something like this).

Good idea, we should try to get an understanding of how people may find their way into docs.

What’s the alternative? Giving write access to everyone with a valid account?

My main concern was avoiding the complexity that describing the task and scope of work would entail. We should definitely document that, perhaps as a supplement to the charter or in another document. However, trying to fit all of that into a name makes it unwieldy.

I’m certainly open to the idea that “core member” and “member” are too far in the “avoid complexity” direction. Maybe we can make it more closely match the tooling and have “committer” and “administrator”? Both would still require a description of the type of work expected, but they might be a little more obvious.

I’m open to this if that’s the general consensus. As I said above, my main concern was avoiding a situation where no one takes the role because it sounds like more than they can commit to. I wonder if instead of trying to have a person at the “top” to take this role if we should have several based on areas. So maybe a list like:

  • Quick Docs coordinatior
  • Release Notes coordinator
  • General docs coordinator (this person works with other generic release docs as well as coordinating help for other teams)
  • Tooling coordinator

One person could take on multiple of those roles, but then the scope is at least narrowed somewhat. And those roles can change independently as needed. The meeting chair would rotate on a weekly basis.


4 posts were split to a new topic: Not using git for docs

From the feedback on this thread and the discussion in yesterday’s meeting, I’ve edited the draft to

  1. Change “core member” to “board member”
  2. Add a minimum number of votes (with a time-based safety valve)

I’ll wait until tomorrow to add this to the team site in case anyone notices any last-minute show stoppers.

1 Like