Community management for documentation contributors and the Docs Workgroup
Home Page: https://docs-community.readthedocs.io/en/latest/
License: Creative Commons Zero v1.0 Universal
TODO:
PEP 732 – The Python Documentation Editorial Board was accepted last month, which formed a Documentation Editorial Board to replace the old Documentation Working Group.
Let's update this repo's docs to reflect this.
Please could the EB take care of updating https://docs-community.readthedocs.io/en/latest/workgroup/index.html?
There's lots of stuff there about (old WG) practices which the new board is best placed to update. I expect a lot can be deleted and/or replaced with a link to the PEP.
An open issue that you may be able to resolve.
This came up at the 2021 Language Summit.
“Thomas and Ee to address.”
(Idea from Scott Shawcroft at the 2021 Language Summit.)
python/cpython#92199 (comment):
It is not related to this PR, but if some item is mentioned multiple times in one paragrafph, I prefer to keep link only in one of them (usually at the first occurrence).
:class:`!OpenerDirector`or``OpenerDirector``. Too many duplicated links do not make the text more readable.
I agree with @serhiy-storchaka; this would be good to mention in the docs style guide.
There seems to be general consensus that diátaxis is a great theoretical model for structuring documentation.
However, using it – restructuring Python's docs – is a monumental task that needs some planning upfront.
@AA-Turner mentioned on the recent meeting that it would be good to start by charting the starting point: where on the Diátaxis chart do individual sections of the docs fall?
With that info we should be able to start planning where they should fall, and restructure/rewrite accordingly.
There's this open issue right now on British vs American spelling:
In the past, there's been some merged PRs on similar smallish consistency/grammar issues:
python/cpython#2787
python/cpython#25985
However, there are also these other comments that seem to resist against trivial changes:
python/cpython#58372 (comment)
python/cpython#62480 (comment)
The sense that I'm getting is that trivial / minor grammatical / consistency issues are generally not considered if it's either unreported, too large such that it'll take more core dev reviewing time than it's worth in improvement, or touches on somewhat historical docs. Would this be an accurate summary on whether to consider committing small changes?
https://developers.google.com/search/docs/fundamentals/seo-starter-guide
Google provides tool for analyzing your website performance: https://developers.google.com/search/docs/fundamentals/seo-starter-guide
I think it needs the domain owner to do it, so perhaps someone from PSF infra team needs to look into this.
A question from the Typing summit:
How to communicate the philosophy of type annotations in Python?
There's a nice community around typing that is responsive to ideas and thoughts.
We'll be modeling this after the application process for Code of Conduct workgroup members. See https://mail.python.org/pipermail/psf-community/2018-April/000488.html as an example
How to improve docs.python.org's SEO ranking?
Come up with action items on how the SEO can be improved.
An old open issue that you may be able to resolve.
The changelog page is very long:
It's currently 219,974 words, that's longer than Moby Dick (212,794 words)... 🐳
It contains all the NEWS entries back to Python 3.5.0 alpha 1 (February 8, 2015).
It loads okay on deskstop, but my phone struggles to render it, and the browser hangs when trying to search for text.
I tried to check the accessibility report using Google's PageSpeed Insights:
It shows good initial numbers:
But the rest of the report is missing: "Oops! Something went wrong. generic::deadline_exceeded: Render timeout received in extension."
Shall we break the changelog page into smaller, more manageable chunks?
Is there any slack or Discord official community of Python?
Posting here for added visibility.
The Montréal-Python user group is hosting a sprint to work the on the French translation of the Python documentation until the end of the month. We are focussing on 3.9 for this sprint with aspirations to run another one in the fall to focus on 3.10.
More details here: https://mtlpy.org/en/2021/04/python-fr-sprint/
This is an old issue which I believe is within the remit of the docs WG. (Please correct me if I am misunderstanding what the WG does).
The second Docs WG meeting will be held Monday, March 7th, 22:00 UTC on Discord. If you already have an account there, please join with sMWqvzXvde. Or contact me at [email protected] for a direct link -- this should be public, but I want to avoid any invite-harvesting bots.
I've cleaned up the HackMD document, so we can reuse it. Feel free to add agenda items there: https://hackmd.io/_vyolH-NR3GQHoOUjqdzuQ
I have been browsing various documentation sites, as part of exploration for #1, and I quite like how React has handled their presentation for the documentation translations: https://reactjs.org/languages
By having a separate page, the page can now contain:
I think all of these are basically non-feasible for a dropdown-based language selector like we have today on docs.python.org.
An old open issue that you may be able to resolve.
An old open issue that you may be able to resolve.
From time to time the discussion arise about moving docs.python.org to readthedocs, there's even an experimental python.readthedocs.io.
I think there's many pros and cons of using readthedocs.
I'd personally be in favor of it if we (the PSF) support them (the cpython Doc is a big one with a lot of traffic, it take around 24h of CPU to build all versions × languages with all PDF A4, PDF letter, HTML, plaintext, epub).
In the other hand it's not an easy task, among other things docs.python.org is not only about generating the docs but also hosting history:
(This was discussed at one of the meetings, filing an issue so it isn't forgotten.)
Any kind of reorganization can break existing URLs. Ideally any breakage is intentional rather than accidental. Even more ideally, we add some redirect mechanism.
Brian Skinn's sphobjinv library might be useful for inspecting Sphinx inventories.
Given this project is using read the docs, we may as well use PR preview rendering.
I don't know who is an admin of the project on RTD, though -- @willingc perhaps?
A
The devguide style guide advises against using "CPU":
CPU
For “central processing unit.” Many style guides say this should be spelled out on the first use (and if you must use it, do so!). For the Python documentation, this abbreviation should be avoided since there’s no reasonable way to predict which occurrence will be the first seen by the reader. It is better to use the word “processor” instead.
But it's advice rarely followed. A quick count in the CPython docs (searching for lines with regex "\bCPUs?\b" and "\bprocessors?\b"):
Even the devguide only managed 1 "processor", and it was in the recommendation above to use this word. Compared to 4 "CPU" (1 in the prohibition above and 3 elsewhere).
Well, let's see what some other style guides say.
CPU
All caps. No need to expand the abbreviation on first mention.
Capitalization
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure.
CPU
Abbreviation for central processing unit. Avoid in user materials; use processor to refer to the chip and use computer or system to refer to the computer itself. For guidelines about spelling out abbreviations, see abbreviations and acronyms. See also computer; processor; system.
CPU not specifically mentioned or prohibited.
CPU, CPUs (n.)
Central processing unit. Do not spell out.
This advice was first added to the devguide by Sandro Tosi in January 2012:
python/devguide@3160c41
It was moved from "Documenting Python":
https://web.archive.org/web/20080214225803/http://docs.python.org/dev/documenting
The style guide mentioned there isn't archived, but it was originally part of the Python source. This advice was first added to the main repo by Fred Drake in July 2001:
\begin{description}
\item[CPU]
For ``central processing unit.'' Many style guides say this
should be spelled out on the first use (and if you must use it,
do so!). For the Python documentation, this abbreviation should
be avoided since there's no reasonable way to predict which occurance
will be the first seen by the reader. It is better to use the
word ``processor'' instead.The commit message:
Add a little more information about the usage of some terms where the style guide can use a little clarification, and present some minor specific markup.
Make a few adjustments to conform to the style guide.
I had a poke around the old Python-Dev mailing list but didn't find any mention.
So no specific reasoning for this addition.
I think our recommendation is outdated, and we're clearly not following it.
I think it's okay to use "CPU" without spelling out.
Shall we remove this rule, or update it somehow?
Dump of April's https://hackmd.io/@encukou/pydocswg1 so we can re-use the HackMD for May.
Let's edit and add to https://github.com/python/docs-community/tree/main/docs/monthly-meeting
# Documentation Community Team Meeting (April 2024)
:::info
- **Date:** 2024-04-02
- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-04-02/19:00/Docs%20Meeting)
- **This HackMD:** https://hackmd.io/@encukou/pydocswg1
- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-2nd-april-2024/49574) (for April)
- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))
- **Calendar event:** (send your e-mail to Mariatta for an invitation)
- **How to participate:**
- Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in.
- To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). You need to log in (e.g. with a GitHub account).
:::
By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/).
Please take a second to read through it!
## Roll call
(Name / `@GitHubUsername` *[/ Discord, if different]*)
- Petr Viktorin / `@encukou`
- Hugo van Kemenade / `hugovk`
- Daniele
- Carol / `@willingc`
- Ned / `@nedbat`
- CAM / `@CAM-Gerlach`
- Bradley
- Ashley / `@AWhetter`
-
## Introductions
> If there are any new people, we should do a round of introductions.
## Reports and celebrations
> 60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass.
> This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting.
- [Carol] Docs summit at PyCon US https://us.pycon.org/2024/events/hatchery/docs-summit/
- [Hugo] Modernised font on macOS: [python/python-docs-theme#176](https://github.com/python/python-docs-theme/pull/176)
- [Hugo] I wrote up how to activate tabs in Sphinx docs based on the reader's OS: https://dev.to/hugovk/sphinx-docs-how-to-activate-tabs-for-your-os-pd3
- [Hugo] Python 3.11 is now only accepting security fixes, so very few docs PRs need backporting: https://devguide.python.org/versions/
## Discussion
### Changelog splitting/reduction
No use cases other than "grepping it all" found so far
### [CAM] WarningMessage is undocumented
https://discuss.python.org/t/warningmessage-is-undocumented/48877
Please read the thread and chime in!
### Parameter annotations: `int | float` or `int or float`?
https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196
- [Name] ...
### 'Internal' items
*For and about the Community or Working Group*
- [Name] ...
### Python Project Documentation
*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.*
- [Name] ...
### PEP Workflow
- [Name] ...
## Follow-ups from previous meeting(s)
*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*
- [name=Carol Willing]: [Changelog splitting/reduction](https://github.com/python/docs-community/issues/98). At the February meeting, we had consensus that slimming down the changelog makes good sense. Let's discuss the potential approaches to do so, and try to reach consensus.
- CAM: split by minor release (feature version) would probably make most sense; we could make it more granular.
- Instead of changelog file we could have a changelog directory. Or we could chunk it in the directive. Either way is relatively straightforward.
- Ezio: We have to thing about the use of this changelog; one of those is searching for a particular module/function across all the releases. If we split it in several files, this'll be harder. Maybe we should keep a few latest releases on a single page. Or use tabs and make filtering faster.
- Hugo: On mobile, the page doesn't render well.
- CAM: Are people searching the rendered HTML, or other files. (Petr: i use Ctrl+F quite often)
- Carol: One more use case: When a bug happens, searching for when the feature was introduced.
- There are several issues: the time it takes to build, and the performance on mobile.
- Pradyun: We could make it so that there's still a search across changelogs. We could also add some Javascript to fetch the files and render them in one file.
- CAM: Or we could have one file with everything, and multiple per-version files. It'll still affect build time though.
- Ned: What's the original problem, user experience or build times? Hugo: build time is not the main concern.
- Ashley: What are the use cases of the NEWS file over the What's New pages? Hugo: I only check the What's New.
- Erlend: Do people actually read the changelog, or do they only search it? Does it really have an impact for users if we shorten the changelog?
- CAM: Maybe we should look into the stats at Plausible.
- Carol: For mobile, data can be expensive and slow, so we want this to be responsive and easy to use.
- Hugo: In the Plausible trial, it's the 256th most visited page (4,000 views). What's New was number 98 (18,000 views). There are 10,000+ pages (across 3 versions and several translations).
```
rank, page, views
62 /3/whatsnew/3.11.html 32123
98 /3.12/whatsnew/3.12.html 17967
129 /3.11/whatsnew/3.11.html 11410
140 /3/whatsnew/3.10.html 10199
178 /3/whatsnew/3.8.html 7250
253 /3/whatsnew/3.9.html 4333
256 /3/whatsnew/changelog.html 4226
263 /3.13/whatsnew/3.13.html 4042
277 /3/whatsnew/index.html 3752
435 /zh-cn/3/whatsnew/3.11.html 1993
459 /3/whatsnew/3.6.html 1875
547 /3/whatsnew/3.7.html 1514
553 /3/whatsnew/3.0.html 1488
695 /zh-cn/3/whatsnew/index.html 990
```
- Ned: How are we going to use the numbers?
- CAM: The page size for the what's new is about 3KB, changelog is about 4.6MB. That's quite big if you're not on broadband.
- Pradyun: It looks like we have agreement for splitting by directory. Any concerns with that?
- Petr: If you don't use a changelog for searching across Python versions, there isn't much else to use it for.
- [note taker was in discussion]
- Ezio: Using tabs like we use for the devguide?
- Hugo: It would not solve the downloading/page size issue.
- Ezio: (paraphrased) It would help the DOM rendering issue.
- Action item: @encukou to ask on the issue if there's a known usecase for the changelog where you don't want everything on one page.
- [name=Erlend Aasland]: Evaluate param markup for `eval()` in `Doc/library/functions.rst` (PR [#115212](https://github.com/python/cpython/pull/115212))
- Erlend: Last year (https://discuss.python.org/t/16090) there was a discussion about why we don't use markup for arguments. The consensus seemed to be "let's try it out". I did, and received mostly positive feedback. Now I changed `eval` needs more attention than some weird corner of the stdlib. I merged it; looking for feedback. I have more functions in the pipeline.
- Hugo: +1, it's easier to scan
- Erlend: the issue had a very long history with lots of discussion about how to communicate the meaning of the parameters, before we agreed on a wording that everyone liked. Structured parameter docs make this easier.
- Ned: I wish we could get away with the Sphinx syntax where colons are brackets somehow.
- (Carol: Way back then we didn't have brackets, remember? :)
- CAM: there's also Myst...
- Erlend: Any reservations after seeing it live?
- Carol: One of the concerns is consistency across the whole file.
- Erlend: That's a valid concern. Will try to find some time to change the markup for some other functions in the page. It's not always straightforward to do for some of the more low-level functions like compile.
- Hugo: I think it's good.
- Erlend: One aspect is that this simplifies writing the description. It's more normalized so there isn't so much space for discussion.
- Petr: Maybe we could get a graphic designer comment on the theme.
- Hugo: Tania Allard has offered to help with an accessibilty audit which could help
- Ned: There are disparate styles: `str` is monospace, *code object* is italic
- CAM: We had a big discussion about how to style ``None``; decision was to use monospace but not link it. There are differences in the markup too.
- Ned: Should we link `str` and `dict`? We could just use monospace. Sometimes, the docs canbe over-linked.
- CAM: it's important to distinguish names that exist in Python.
- Carol: Let's ask a UI expert.
- (...)
- We should have a cheatsheet for ReST. The page in the devguide isn't clear for newcomers.
- CAM: Should we expand the current cheatsheet, or have an expanded “getting started” guide?
- Carol: I'm not entirely sure, I'm not making any radical change right now. I was looking into what would be a stumbling point for sprinters and this came up.
- CAM: BTW, in the logging docs, formatter parameter types are auto-linked but not monospaced
- (discussion on tooling)
- Ned: We should start from what we would like to see, and then make the tools do that.
## Next meeting
The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC.
We have a recurring Google Calendar event for the meeting.
Let Mariatta know your email address and she can invite you.Warnings were temporarily disabled in #69. They should be re-enabled.
An open issue that you may be able to resolve.
we should turn this into a modern "how to write a modern interpreter finalization and subinterpreter safe extension module" best practices doc. (beyond the pep)
An old open issue that you may be able to resolve.
So... this morning I'm spiralling into what is almost certainly going to end up being a proposal on python-ideas or the Ideas category on discuss.python.org -- that we adopt the "Teams" concept from PEP 8015.
And... that has confused me about this group -- is the plan for this group to become a PSF work group (i.e. PSF board approved group, fundraising + making hiring decisions, handle all the paperwork around that etc), or is this intended to be closer to what the typing has (just a bunch of volunteers who are interested in the topic), or what the packaging community has (both, with a clear separation between the two)?
I'm thinking that this group will have a similar split in responsibilities as Packaging-WG and the PyPA (see https://peps.python.org/pep-0609/#terminology for language on the relationship).
Filing this on the issue tracker, to serve as a clear place for public discussion on this. :)
Hello, Docs WG! I think it's time to plan the long-overdue monthly meetings.
Carol filled me in on some previous conversations, and I'd like to play the role of a project manager -- help make this actually happen.
I'm envisioning a one-hour meeting call, open to the community (with moderation, obviously).
Would everyone be OK with meeting over 
Discord?
For me it would be convenient to combine this meeting with the Steering Council one, so I'll propose Monday, Feb 7th, 17:30 UTC 22:00 UTC. But I'm quite flexible.
Does this work for you, and if not, what time(s) could you make it? If you don't want to share details here, I'm at [email protected]
@willingc @Mariatta @nedbat @JulienPalard
Edit:
As for the platform, no one seems to be against Discord. If you already have an account there, please join with sMWqvzXvde. Or contact me at [email protected] for a direct link -- this should be public, but I want to avoid any invite-harvesting bots.
At https://docs.python.org/sitemap.xml the link https://docs.python.org/en/3/ does not work
I would like to propose these activities for PyCon 2024, I know it is not relevant to the documentation for Python but I would like to get the opinion of the amazing people who are passionate about documentation and put in so much effort to make our documentation great!
Like other summits, we will invite leaders in the documentation spaces (especially in the Python community) to present some documentation-focused talks. We will also host panel sessions to discuss relevant issues regarding documentation. It would also be great to invite tech writers from companies (e.g. sponsors, those who have good documentation) to join.
It can be part of the "regular" sprint at the end of the conference, however, we should gather projects to put focus on documentation and encourage contribution to it. Or it can be like mentored sprints and have a separate session in the tutorials/ main conference days.
Please let me know what you think. CC @Mariatta who is the awesome PyCon chair of 2023 and 2024
The pinned about page for the Documentation category still has the template placeholder:
https://discuss.python.org/t/about-the-documentation-category/5499
(Replace this first paragraph with a brief description of your new category. This guidance will appear in the category selection area, so try to keep it below 200 characters.)
Use the following paragraphs for a longer description, or to establish category guidelines or rules:
Why should people use this category? What is it for?
How exactly is this different than the other categories we already have?
What should topics in this category generally contain?
Do we need this category? Can we merge with another category, or subcategory?
Let's update it.
An open issue that you may be able to resolve.
Currently the contributions to python-docs-theme are made hard because of the language and version switchers.
I made review a bit easier by adding a github action to build the doc and provide it as a built artifact, so reviewers can just download and test locally.
But still the enhancement of the doc is made hard, for example python/python-docs-theme#46 has been slowed down because of this (sry @obulat).
I once had an idea to enhance the situation: we could provide an "API" on the form of a simple .js file at the root of docs.python.org listing the available versions and languages.
pros:
version.js file and have no switchers.version.js file).cons:
/{LANG}/{VERSION}/ with the language being optional, defaulting to english.Other ideas, and feedback welcome.
This came up in the Python 3.10 release stream -- https://youtu.be/AHT2l3hcIJg?t=5700 for the exact timestamp of when this was proposed in the stream and discussed briefly -- and I noticed that no issue has been filed for this yet so... I'm doing it myself. 😅
I wasn't the person who proposed this, so... there's no bullet list items of what exactly this would be. :)
An open issue that you may be able to resolve.
Wiki.python.org is not mobile friendly.
It would be great to have a mobile theme for wiki.python.org. Though I personally don't have CSS / styling / art skills, so all I can do is provide moral support and perhaps merge the PR 😅
I wasn't able to locate the source code for the wiki, and I wasn't sure who "owns" or "hosts" the wiki, so I asked in The PSF's Discourse: https://discuss.python.org/t/wiki-python-org-is-not-mobil-friendly/8700
Some info:
Some thoughts and questions:
We need to add <meta> tags to the output of sphinx documentation.
It looks like this is supported using the meta directive
https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta
Example:
.. meta::
:description: The reStructuredText plaintext markup language
:keywords: plaintext, markup language
Some meta tags we should have:
titledescriptionSome advice according to: https://ahrefs.com/blog/seo-meta-tags/
Title meta:
Description meta:
An open issue that you may be able to resolve.
The docs are a bit of a ghost town. Remove the unnecessary bits, consolidate the necessary ones, and generally make it better.
(But keep in mind it should be living documents: we don't need book-quality prose.)
In 2019 Dustin Ingram made this chart of the Python release cycle: https://python-release-cycle.glitch.me/
Jeff Triplett and I have forked to make one for Django and Drupal respectively. It's a simple static site: some HTML, JS and CSS using a Gantt chart from Google Charts:
Dustin recently asked:
Hugo, do you think there's any appetite for putting this in more official docs or web properties somewhere? I think there was talk about that at some point but never saw it happen.
I think it would be good, it has come up before a couple of times:
If so, we have a number of options.
We could:
Move this page under https://github.com/python/ as a standalone static page
Create a new chart integrated into either of those pages
For option two, I made a proof of concept using https://github.com/mgaitan/sphinxcontrib-mermaid to render a Gantt chart on the devguide: https://hugovk-devguide.readthedocs.io/en/mermaid/versions/
Right now it duplicates the dates, but once python/devguide#884 is merged, we could generate them from the CSV.
Let's discuss in today's docs community meeting.
Do we want to add styling for good/bad code blocks to PEPs?
For an epxample, look at pep8.org, a third-party (and outdated) rendering of PEP 8
The main difference between it and the new style proposed for PEPs is the red & green indicators on what to do vs. what not to do.
I've just read the dangerous "naive" SQL code in PEP-0675 and thought it could use a similar "don't copy this" indicator. There surely are many other examples.
Of course everything should be covered in prose for screen readers and color-blind people, but for many people colors could aid understanding.
Would it be useful in docs as well?
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.