python/docs-community

Community management for documentation contributors and the Docs Workgroup

docs-community's Issues

Review bpo-23312: google thinks the docs are mobile unfriendly

An open issue that you may be able to resolve.

Enhancing the switchers setup

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).

Solution 1

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:

• It removes the switchers ugly hack in docsbuild-scripts.
• It make the theme easy to test locally: just drop a versions.js at the root with some sample data.
• A project using our theme with no need for switchers will not use a version.js file and have no switchers.
• A project using our theme with the need for switchers could set them up easily (add a version.js file).

cons:

• This is already the case, but we should be aware of the SEO penality that we could have if we redrow the page after load to render the switchers.
• The impementation will probably be tied to our specific hiearchy: /{LANG}/{VERSION}/ with the language being optional, defaulting to english.
• It may not follow the current state of the art of doing this, as I did not reviewd how other themes do this, how readthedocs does it, how for example https://docs.djangoproject.com/en/3.1/ does it.

Other ideas, and feedback welcome.

cc @pradyunsg @obulat

docs-community: Enable preview rendering for pull requests

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

Having a "fast path" for documentation contributions

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. :)

Move language selection to a dedicated page?

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:

• Clear indicators for the "state" / "completeness" of the translation efforts, like "In Progress" and "Needs Contributors".
• Clear links to contribute to each of the language-specific translation efforts.
• Callout to a documentation page, for folks interested in contributing additional languages.
• A lot more space to present translations across many languages. :)

I think all of these are basically non-feasible for a dropdown-based language selector like we have today on docs.python.org.

Review bpo-21314: Document '/' in signatures

An old open issue that you may be able to resolve.

Style guide suggestion: Avoid duplicate links

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.

Review bpo-36329: use the right python "make -C Doc/ serve"

An open issue that you may be able to resolve.

Diátaxis: Where are we?

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.

Review bpo-40245: Add description meta tags to docs.python.org

An open issue that you may be able to resolve.

Discourse: Move Docs category to the top level

Review bpo-13386: Document documentation conventions for optional args

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).

Migrate these docs to docs-community.python.org

Roles/styles for good/bad code blocks in PEPs

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?

Docs WG monthly meeting #1

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.

Add automation to prevent breaking URLs

(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.

[PyCon 2024] Documentation summit and Documentation sprint

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!

Documentaion summit

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.

Documentation sprint

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

Discourse: fill in "About the Documentation category"

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.

Re-enable deprecation warnings

Warnings were temporarily disabled in #69. They should be re-enabled.

#70 (comment)

Review bpo-5901: missing meta-info in documentation pdf

An old open issue that you may be able to resolve.

Docs WG monthly meeting #2

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

Do we need the CLA for documentation PRs?

French translation sprint

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/

Mobile friendly theme for wiki.python.org

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:

• Hosting of the wiki is configured in psf-salt: https://github.com/python/psf-salt/blob/8c29e89e500bd1ad48c112e0144d574e89d13e01/pillar/base/moin.sls#L2-L7
• The wiki is powered by moinmoin
• General documentation on how to develop moinmoin theme: https://moinmo.in/MoinDev/ThemeDevelopment
• wiki.python.org is using europython moinmoin theme: http://moinmo.in/ThemeMarket/Europython.
• Source code of the europython theme is currently on Mercurial: http://hg.sheep.art.pl/moin-europython/ (what's the license)

Some thoughts and questions:

• We can fork the europython theme and improve it?
• Or perhaps we should develop a theme for us and make it look closer to python-docs-theme, or python.org?
• Or perhaps we should just use a pre-existing more modern moinmoin theme? Looks like the official theme itself is quite mobile friendly?

Changing docs for trivial issues

There's this open issue right now on British vs American spelling:

python/cpython#82221

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?

Devguide: Explain why we need the CLA

How to communicate the philosophy of type annotations in Python?

A question from the Typing summit:

How to communicate the philosophy of type annotations in Python?

• Beginners don't need annotations
• "Catching bugs" is how to sell it to your engineering director :-)
• Adding improvements like new Union to simplify the syntax

There's a nice community around typing that is responsive to ideas and thoughts.

Help needed: Community platform

Is there any slack or Discord official community of Python?

Document the Editorial Board in this repo

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.

• https://github.com/python/docs-community/blob/main/README.md -> PR #99
• https://docs-community.readthedocs.io/en/latest/workgroup/index.html

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.

Suggestions from Python Language Summit

1. From Greg Smith:

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)

Add meta tags to docs.python.org

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:

• title
• description

Some advice according to: https://ahrefs.com/blog/seo-meta-tags/

Title meta:

• Write a unique title tag for each page;
• Be brief, but descriptive;
• Avoid generic and vague titles;
• Use sentence case or title case;
• Create something click-worthy—not clickbait;
• Match search intent;
• Include your target keyword where it makes sense;
• Keep it under 60 characters.

Description meta:

• Write a unique description for each page;
• Try to summarize content accurately;
• Avoid generic descriptions;
• Use sentence case;
• Create something click-worthy, not clickbait;
• Match search intent;
• Include your target keyword where it makes sense;
• Keep it under 160 characters

Review bpo-36795: "make venv" failed in Docs

An open issue that you may be able to resolve.

Bug in sitemap ?

At https://docs.python.org/sitemap.xml the link https://docs.python.org/en/3/ does not work

Research ways to improve SEO

How to improve docs.python.org's SEO ranking?

Come up with action items on how the SEO can be improved.

Style guide: permit "CPU"?

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"):

• 74 "CPU"
• 48 "processor"

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).

Other style guides

Well, let's see what some other style guides say.

Google:

CPU
All caps. No need to expand the abbreviation on first mention.

Red Hat:

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.

Apple:

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.

Microsoft:

CPU not specifically mentioned or prohibited.

Bishop Fox

CPU, CPUs (n.)
Central processing unit. Do not spell out.

Archaeology

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:

python/cpython@9120df3

  \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.

Suggestion

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?

Migration of theme to modern responsive theme

python/devguide#679

Host the Python docs on ReadTheDocs

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:

• https://docs.python.org/release/ (this is all the tagged commits in the cpython repo)
• https://docs.python.org/2.0/ (yes we keep old versions, and I'm not willing to see this disapear)

Post the application process for workgroup members

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

Have python.org search also search the docs

(Idea from Scott Shawcroft at the 2021 Language Summit.)

Shut down and archive https://legacy.python.org/

This came up at the 2021 Language Summit.
“Thomas and Ee to address.”

What's the intended organisation of people here?

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. :)

Review bpo-21956: Doc files deleted from repo are not deleted from docs.python.org.

An old open issue that you may be able to resolve.

Review bpo-43614: Search is not beginner friendly

An open issue that you may be able to resolve.

Add release cycle chart

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:

• https://github.com/jefftriplett/django-release-cycle
• https://github.com/hugovk/drupal-release-cycle

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:

• python/cpython#69483
• python/pythondotorg#1302

Options

If so, we have a number of options.

We could:

• Move this page under https://github.com/python/ as a standalone static page

  • Either link to the static page, or
  • figure out a way to integrate it to https://www.python.org/downloads/ and/or https://devguide.python.org/versions/

• Create a new chart integrated into either of those pages

Proof of concept

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.

Further

Let's discuss in today's docs community meeting.

Cut the whale of the changelog into manageable pieces?

The changelog page is very long:

• https://docs.python.org/dev/whatsnew/changelog.html

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:

• https://pagespeed.web.dev/analysis/https-docs-python-org-dev-whatsnew-changelog-html/9zu7fhwlzu?form_factor=mobile

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?

Review bpo-15871: Online docs: make index search always available.

An old open issue that you may be able to resolve.

Use Sphinx for pep builds and better rendering

TODO:

• Deploy on RTD and GH-Pages
• Determine after both are deployed when should each be used. I could see RTD for PEP docs similar to devguide and gh-pages to perhaps integrate with Python dot org

Clean up docs-community.readthedocs.io

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.)

Analyse docs.python.org using Google Search Console

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.