|
| 1 | +# Documentation Community Team Meeting (August 2022) |
| 2 | + |
| 3 | +- **Date:** 2022-08-01 |
| 4 | +- **Time:** [21:00 UTC]<!--(https://arewemeetingyet.com/UTC/2022-08-01/21:00/Docs%20Meeting)--> |
| 5 | +- **This HackMD:** https://hackmd.io/@encukou/pydocswg1 |
| 6 | +- **Discourse thread:** https://discuss.python.org/t/documentation-community-meeting-august-1/17847 |
| 7 | +- **Calendar for future meetings:** (send your e-mail to Mariatta for a calendar invitation) |
| 8 | +- **How to participate:** |
| 9 | + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. |
| 10 | + |
| 11 | +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). |
| 12 | +Please take a second to read through it! |
| 13 | + |
| 14 | +## Roll call |
| 15 | + |
| 16 | +- Mariatta / `@Mariatta` |
| 17 | +- Petr Viktorin / `@encukou` |
| 18 | +- Hugo van Kemenade / `@hugovk` |
| 19 | +- Ned Batchelder / `@nedbat` |
| 20 | +- Ezio Melotti / `@ezio-melotti` |
| 21 | +- CAM Gerlach / `@CAM-Gerlach` |
| 22 | +- Jim DeLaHunt / `@JDLH` |
| 23 | +- Daniele Procida |
| 24 | +- Pradyun Gedam |
| 25 | +- Erlend Aasland / `@erlend-aasland` |
| 26 | + |
| 27 | +## Discussion |
| 28 | + |
| 29 | +### How to edit HackMD doc? |
| 30 | + |
| 31 | +- Log in (with GitHub or something) |
| 32 | +- Then use the pencil button at the top of the page |
| 33 | + |
| 34 | +### Diataxis Workshop |
| 35 | + |
| 36 | +- 70 ppl signed up, ~35 are accepted. |
| 37 | +- Could let a few more ppl in, but it's probably best to repeat sometime later. |
| 38 | +- Thanks Mariatta, Ned & CAM. |
| 39 | + |
| 40 | +### New Python Docs theme |
| 41 | + |
| 42 | +- Pradyun talks about Lutra, a new theme for "big" docs. (Pradyun's existing theme, Furo, is for "smaller docs" -- it puts everything in the sidebar) |
| 43 | + - Can we see the sample? |
| 44 | + - https://pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/ |
| 45 | + - CAM: How's this different from Furo? |
| 46 | + - 1. Didn't want to do too many things with Furo -- it does what it does well |
| 47 | + - 2. Freedom from backwards compatibility concerns |
| 48 | + - Mariatta: Can it handle CPython docs build process? |
| 49 | + - Pradyun is looking into the docs-build script |
| 50 | + - Daniele: You showed us two different modes of Lutra |
| 51 | + - Pradyun: there are 5 modes. Configured in conf.py |
| 52 | + - Ned: the different modes seem complicated, when Python docs will use just one mode |
| 53 | + - Pradyun: I imagine python-docs-theme will customize this further, e.g. use the python.org header |
| 54 | + - Daniele: furo works for smaller sites, but its navigation model is powerful, allowing the user to internalize the information architecture. In Lutra's mode, which one also prioritize docs architecture within its navigation model? |
| 55 | + - Pradyun: all of them, just exposed in slightly different ways. |
| 56 | + - CAM: Enabling and following a model that more closely matches the existing structure of the Python Docs (at least initially), even if it isn't ideal, is important for ensuring acceptance of the new theme and reducing friction to an acceptable level given how much this is already changing. |
| 57 | + - Ned: what's the plan here? Pradyun will write a doc, etc |
| 58 | + - Pradyun: working on it, hopefully this weekend |
| 59 | + - Petr: Who will write a PEP? |
| 60 | + - Ned: Why do we need a PEP? |
| 61 | + - Daniele: when it comes to adopting diataxis, but it's a decision that should be taken after the workshops. After the workshops people will have clearer idea and implications of what it will mean for the docs. If there is a strong consensus, that's when we should work that decision into a PEP. It needs to be really understood by the people making small changes. The PEP of styling is the same. |
| 62 | + - Petr: Diataxis is more about direction, should be more of a Discourse discussion other than a PEP |
| 63 | + - Ned: How much decision-making we need ahead of time before starting working with Diataxis. |
| 64 | + - Petr: the purpose of the PEP is to make sure you consider everything about the problem, make sure everybody that should be heard is heard, make sure everything is documented. If you can get to that goal some other way, then we don't need a PEP. |
| 65 | + - Daniele: it's like a deciding: Are we going to climb up that mountain? Which mountain? Once we decided on which mountain, we better make sure we're equipped for that, we don't need all the plans, but still need agreement. |
| 66 | + - Ned: What are we writing in this PEP? It can be just one paragraph, or 10 pages. |
| 67 | + - Petr: There is a PEP template ([PEP 12](https://peps.python.org/pep-0012/)). |
| 68 | + - Ned: How is a PEP ... ? |
| 69 | + - Daniele: We need to have a clear picture of where we want to go. |
| 70 | + - Petr: let's leave this for after the workshop |
| 71 | + - Pradyun: PEP is our tool for consensus building. |
| 72 | + - Hugo: With [PEP 676](https://peps.python.org/pep-0676/): work was done ahead before the PEP, and we didn't really know who was going to make the decision of it, and after the PEP there was more clarity of who makes the decision. |
| 73 | + - CAM: a PEP can be design docs or detailed plan, but can also be a rationale. |
| 74 | + - Pradyun: We don't want to put in process that makes it more diffcult for people to contribute. |
| 75 | + |
| 76 | +## Next meeting |
| 77 | + |
| 78 | +The docs team meets on the first Monday of every month. |
| 79 | + |
| 80 | +We have a recurring Google Calendar event for the meeting. |
| 81 | +Let Mariatta know your email address and she can invite you. |
0 commit comments