Documentation Governance

Every team member with a GitHub account is empowered to make pull requests to change any part of the documentation, and every team member is encouraged to review any pull request.

Ideally, pull requests should be assigned to team members who are subject matter experts. For example, changes to the file were assigned to a lawyer (who happens to be a copyleft and FLOSS expert). If you're not sure who to assign the PR too, you might want to ask in the #docs channel.

Governance driven by practice area and working groups.

We encourage each team at CivicActions (aka Working Group, Practice Area, Guild, etc.) to take ownership over their respective documentation. To that end, changes to files in certain directories require at least one review and approval from a member of the respective team, and members of those teams will be notified of that PR. For example, changes to the 060-engineering directory requires at least one review and approval from a member of the Engineering Team.

These teams are listed on GitHub as subteams of the main CivicActions team. If you want to join one of those teams, you can go to the team page and "Request to join". A maintainer of that team will receive a notification and can approve you. You can see the maintainers from the team page, feel free to bug them for an approval.

Directory in docs/ Subteam (Working group / Practice Area)
000-contributing Docs
010-welcome-to-civicactions Anyone
020-about-us Anyone
030-policies Management
040-employee-handbook-us Legal
050-how-we-work Anyone
060-engineering Engineering
070-project-management Project Managers
080-sales-and-marketing Anyone
090-peopleops Management
100-security Security

Ideally, each of the above working groups have their own backlog of documentation tasks, and make documentation a regular part of their workflow.

@todo or will we use GitHub issues, with issue tags for each team?

The CODEOWNERS file in the top level of this repo maps the governance of docs/ directories to their respective GitHub teams and CivicActions practice areas, and automatically assigns pull requests to that team for review, when a PR is submitted that.

GitHub team management

GitHub team management is an ongoing responsibility of the Docs working group, but is generally taken care of during onboarding.

To add someone to a team, go to the subteam page and click Add a member.