CPython Documentation Workgroup#

Purpose & Common Goals#

The purpose of this working group is to support the larger efforts of improving and maintaining CPython’s Documentation through documentation curation, internationalization, and special projects. It will largely focus on efforts such as CPython documentation, tutorials, how-to documents, dev guide and other documentation in support of the PSF’s mission of expanding the users of Python globally. Quality and effectiveness will be key goals as will be building a diverse team of community members, documentarians, and core developers.

Things the DocWG could do:

  • Develop the governance model for docs

  • Be the steering council for docs

  • Be the authors of doc guidelines

  • Be the authors/editors of docs

  • Request grant funding from PSF, if needed.

  • Form an editorial board for docs including core devs, educators, and documentarians in the Python community

Active Time#

This workgroup will be active indefinitely while supported by the Python Steering Council.

Core Values & Internal Government#

The core values for this group are:

  • Respect

  • Support

  • Positive Atmosphere

  • Constructiveness

  • Integrity

The workgroup adopts the PSF Code of Conduct (https://www.python.org/psf/codeofconduct/). Any actions (found by a majority) made against the principles in the Code of Conduct will result in the acting person being removed from the workgroup.

Rules & Guidelines#

  • At any time the Python Steering Council may, at its discretion, add any number of non-voting observers to the working group to observe and participate in discussion.

  • The group’s purview includes the Sphinx documentation included in the Python source repository, including the doc theme, as well as separate projects such as the developer guide. Translations and infrastructure will be managed by Julien Palard or a Steering Council appointed member.

  • The group will also maintain documentation of meetings and best practices.

  • The editorial board will include people outside of the core developers who are tech writers or educators.

Decision Making Procedures#

Decisions will be done using the voting procedures outlined below. Anyone may propose or request a topic for a decision.

  • In general, a topic for decision should address one of the workgroup’s goals:

  • Improve or maintain the state of Python’s documentation effort by some noticeable or measurable amount.

  • Increase the participation of contributors to documentation

When adding new members to the working group, prospective members must send an email to introduce themselves along with a description of why they want to be a member and what they bring to the process. Approval of new members will be decided using the voting procedures detailed below.

Voting#

A vote for any proposal will last for 5 days, or when all voting members have voted, whichever comes first. For a proposal to be successful it must have at least two +1’s, more +1’s than -0’s, and no -1. Voting may be done in any venue given agreement of all voting members.

Communication Plan#

The working group will communicate via the Documentation category on Discourse (http://discuss.python.org).

The existing Doc-SIG mailing list will continue but will not be the primary communication method for the workgroup or for recruiting additional contributors. From time to time the working group will post announcements, such as meeting details, to the Doc-SIG.

The group will also meet on a regular basis to discuss the state of Python’s documentation. Topics might include:

  • The size of the documentation PR backlog, whether it’s growing or shrinking, and what to do about it.

  • Which parts of the documentation require updating most urgently.

  • New documents/sections that should be created to meet community needs.

The monthly meeting will be held using the PSF’s preferred conference meeting tool.

Budget#

The working group will not require a dedicated budget in its initial phase. If needed, the working group may ask the board of directors for any funds needed (for meetings, writers, translators, software development, etc.).

Participants#

The Python Steering Council are permanent members of this working group. The initial workgroup members include:

  • Carol Willing

  • Ned Batchelder

  • Mariatta Wijaya

  • Julien Palard (Lead, Infrastructure/Localization)

The workgroup may expand to up to 20 members with a 25% or higher representation of community who are not core developers.

The Workgroup members will act as the Editorial Board and will make decisions on controversial content, if needed.

Although not part of this workgroup, a Documentation Team will also be created. The Documentation Team will be contributors to documentation who participate regularly to CPython documentation and monthly meetings (synchronously or asynchronously). A goal of this team will be to build a global community around CPython documentation.