Skip to content

Commit 7fa1a96

Browse files
Mariattahugovknedbatezio-melotti
authored
Add Editorial Board Meeting Notes from Feb-Aug '24 (#12)
Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Ned Batchelder <[email protected]> Co-authored-by: Ezio Melotti <[email protected]>
1 parent febc2cd commit 7fa1a96

File tree

5 files changed

+372
-0
lines changed

5 files changed

+372
-0
lines changed

‎updates/2024-02-12-editorial-board-update.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Meeting Notes: Python Docs Editorial Board
2+
3+
## February 12, 2024
4+
5+
## Attendees
6+
7+
Mariatta, Ned, Joanna, Guido
8+
9+
10+
## Agenda
11+
12+
1. What project do we want to deliver first? Here are some ideas to start the discussion:
13+
14+
a. Define scope and outline for new intro tutorial
15+
b. Define scope and outline for new landing page
16+
c. Inventory/audit a section of the docs
17+
d. Personas (see #3 below)
18+
19+
20+
2. What does the docs community need from us most right now? Here are some ideas to start the discussion:
21+
22+
- How-to discussion
23+
- First-person discussion
24+
- A more thorough and more skimmable style guide
25+
26+
3. [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -> see editorial-board GH repo
27+
28+
- Function parameters: bulleted or not
29+
- Examples: how to integrate into the docs
30+
- Type hints
31+
32+
4. Do we have an idea of what type of learner/user we need to optimize the docs for?
33+
34+
- Wait until Carol is back
35+
36+
5. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
37+
38+
6. Will the editorial board give an update at the language summit or PyCon?
39+
40+
- The language summit isn’t even announced yet. We’ll think about it next time
41+
42+
## Notes
43+
44+
1. Let’s begin with a relatively small project. 1b from above. It is concrete, and we can propose implementation and refine it quickly.
45+
46+
2. 2a is a bigger issue, but is important. (will affect 2b)
47+
48+
3. Recommendation: don’t use first-person for new docs.
49+
50+
4. Howto doc: we might preserve some historical content. Some docs may be marked as “historical doc”, keep them, but might get changed. Add a disclaimer at the top.
51+
52+
5. Add reminder to future contributors not to use those as a template.
53+
54+
6. PR churn. Docs changes don’t need to follow the same guidelines.
55+
56+
7. Style guide:
57+
- In devguide now, update it
58+
- https://devguide.python.org/documentation/style-guide/
59+
- Some things should be in the style guide
60+
- First person, terminologies like master/slave, should be there
61+
- Big O notation should be in the Howto part of the style guide
62+
- The EB will own this (and create issues and PRs)
63+
- Should still be on devguide
64+
65+
8. Discovery: 🔒 [Docs Style Guide](https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit#heading=h.hflx14peuyef)
66+
67+
9. Mariatta to create a Gdrive folder to be shared with PDEB
68+
69+
10. Need an announcement about https://github.com/python/editorial-board, that we're here. The readme should tell people how to be involved and how to ask for help.
70+
- On Discourse
71+
- In the README of docs-community GitHub repo
72+
- DevGuide
73+
- And PEP 732
74+
75+
11. Docs Discord server: we shouldn’t need to be the owner.
76+
77+
12. Discuss: what type of learner we need to optimize the docs for?
78+
- We wait until Carol is back
79+
- We’ll start an async collaboration in a new Google Doc
80+
- There is a way to get notification of changes in Google Docs (need to be set up per-doc):
81+
- Click the “comment” button
82+
- Click the bell to set notifications: you can get notified of all content changes
83+
84+
13. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
85+
- What are the types of contributors?
86+
- Core devs, triagers -> already know the way
87+
- For non core devs: First time OS contributor, vs experienced OS contributor
88+
- Non developers
89+
- Not-primarily english-speaking contributors
90+
91+
14. Guido’s request: Not having links that are hidden unless you hover
92+
93+
15. A tutorial on how to successfully contribute to the CPython docs.
94+
95+
16. CPython docs links to GitHub source code if clicked on the “Show Source” link. Is this good?
96+
- Some pages get rendered (pprint.rst), some show as raw rst (functions.rst)
97+
98+
17. What type of contributors who can make the biggest impact, that we are currently overlooking?
99+
- Tech writers
100+
- Challenge: who to listen to. PR reviews can be noisy.
101+
- Member vs Contributor
102+
- But what if even core devs conflict with each other.
103+
104+
18. Can we have volunteers/helpers to help people with pull requests?
105+
- Could be similar to the Djangonauts: have someone who will help new contributors with PRs. Captains, navigators, etc
106+
- Or less structured.
107+
- Avoiding using the word “mentor” because it seems to be establishing a formal relationship
108+
109+
110+
## Action items
111+
112+
* Style Guide:
113+
Update the style guide with some new recommendations: first-person, terminologies
114+
* Ad campaign:
115+
116+
More detail on #10 of the above notes:
117+
* Start the async exploration of who our learners are
118+
* Start the async explorations of what kind of contributors we want to help
119+
* Specify that Python wiki is out of scope in PEP 732: https://github.com/python/peps/pull/3663
120+

‎updates/2024-03-11-editorial-board-update.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Meeting Notes: Python Docs Editorial Board
2+
3+
## March 11, 2024
4+
5+
## Attendees
6+
7+
Mariatta, Ned, Joanna, Guido
8+
9+
10+
## Agenda
11+
12+
1. What project do we want to deliver first? Here are some ideas to start the discussion:
13+
14+
a. Define scope and outline for new intro tutorial
15+
b. Define scope and outline for new landing page
16+
c. Inventory/audit a section of the docs
17+
d. Define learner personas
18+
19+
20+
2. What does the docs community need from us most right now? Here are some ideas to start the discussion:
21+
22+
- How-to discussion
23+
- First-person discussion
24+
- A more thorough and more skimmable style guide
25+
26+
3. [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -> see editorial-board GH repo
27+
28+
- Function parameters: bulleted or not
29+
- Examples: how to integrate into the docs
30+
- Type hints
31+
32+
4. Do we have an idea of what type of learner/user we need to optimize the docs for?
33+
- 🔒 [Discovery doc about learners](https://docs.google.com/document/d/1ILusuBaAoxUzm1NDOuiS3sZYePDVB5YcY7RoLkXyfI0/edit?usp=sharing)
34+
- [Thoughts about growth in users and approach](https://discord.com/channels/1100135599077331024/1100135599077331028/1216838941723070534)
35+
36+
5. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
37+
38+
6. How do we decide on issues for our agenda?
39+
Is e.g. https://github.com/python/cpython/pull/116595 suitable to discuss here?
40+
41+
42+
43+
## Notes
44+
45+
Guido: We didn't actually go through that agenda at all.
46+
We discuss what our priorities are.
47+
We also didn't review last month's action items.
48+
49+
50+
1. Python growth for the next decade will be driven by non CS folks, new users, non technical.
51+
2. Existing tutorial is the "what"
52+
3. Python has a rich ecosystem, you can get a lot of things done without needing the full scope of the stdlib. We should have more docs for it.
53+
Example docs:
54+
- https://github.com/sandiegopython/intro-to-python/
55+
- Jessica McKellar’s intro: https://www.youtube.com/watch?v=rkx5_MRAV3A
56+
4. We need an introduction to Python docs. Current official Tutorial isn’t targeting new non-technical learners. They don’t know where to start. Other resources exist elsewhere. But it would be useful to have a beginner’s guide within docs.p.o
57+
- Do we need to cover everything? Lots of people write guides to Python
58+
- Official docs could have a curated list of useful docs.
59+
60+
5. Options:
61+
- Better landing page?
62+
* It needs to be better for newcomers, but also for people who are already experienced and already know their way around the docs.
63+
* Come up with a refresh of the docs.python.org landing page, more user friendly and welcoming/inviting.
64+
* Tooltips/ Guided tours -> need cookies.
65+
Just provide a link instead of interactive.
66+
- Action item:
67+
* Look at front page of docs.p.o and decide which ones should be more prominent
68+
* Come up with a short: (3 page) tutorial. Carol will start an outline.
69+
* Document our philosophy, explain the different target users and where they can find the docs they need.
70+
- Glossary
71+
- Define other user personas first?
72+
6. Docs community meeting. Anything we should know?
73+
- What to do with Changelog.
74+
- Directives changes in the rst. Need to improve the devguide for it.
75+
- Typographic markups. Still under discussion on Discourse.
76+
- Think about the outcome first and toolings next.
77+
- Accessibility checking. UI/UX. Italics or not.
78+
7. Ned is talking to a university professor who is building their own IDE/notebook.
79+
- They see this as a hurdle for teaching Python to students

‎updates/2024-04-08-editorial-board-update.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Meeting Notes: Python Docs Editorial Board
2+
3+
## April 8, 2024
4+
5+
## Attendees
6+
7+
Mariatta, Ned, Joanna, Guido
8+
9+
10+
## Agenda
11+
12+
1. What will be our Doc Summit participation?
13+
- Who will be attending? Carol, Ned
14+
- Lightning talk: submit: https://docs.google.com/forms/d/e/1FAIpQLSe1n3YMIRnrWhoSSC29yM1w_IucgrY4D6RM3infhaNELFeJSg/viewform
15+
- TODO: Carol will put together some bullets
16+
2. Prepare an “elevator pitch” kind of thing for Editorial Board: it could just point to our repo too?
17+
3. Advice: If you’re going to run a meeting, run the meeting (including cutting and moderating, stopping people from going on and on)
18+
4. Bring up in next community call:
19+
- Are there clear possibilities that you can share with the editorial board, so we can make a decision.
20+
5. Carol or Ned to come up with the options.
21+
6. Warning Sphinx?
22+
- Multiple types: https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/20
23+
TODO: Ned will post on the thread to try to come to closure. What are the current options?
24+
- WarningMessage is undocumented: https://discuss.python.org/t/warningmessage-is-undocumented/48877
25+
7. No meeting in May because of PyCon US. We’ll discuss async until June.
26+

‎updates/2024-06-03-editorial-board-update.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Meeting Notes: Python Docs Editorial Board
2+
3+
## June 3, 2024
4+
5+
## Attendees
6+
7+
Mariatta, Ned, Carol, Joanna, Guido
8+
9+
10+
## Old Action Items
11+
12+
Where are we with the action items from April 8?
13+
14+
1. Bring up in the next community call: Are there clear possibilities that you can share with the editorial board, so we can make a decision?
15+
- Ned has been attending, but can’t tomorrow. They have not been coming up with things they want us to do.
16+
- Give them immediate feedback: we will decide if you create an issue.
17+
- Sometimes the problem isn't framed appropriately
18+
- Carol will attend tomorrow.
19+
- Todo: be clear to the docs wg that we will decide if you open up a ticket
20+
21+
2. Eric Matthes said: wants to see us have more guiding principles before getting involved,
22+
23+
3. Todo: create a dir in the GitHub repo and move there?
24+
- Google Drive?
25+
- Todo: move or link the docs to the GitHub repo
26+
27+
4. NEW Action item: communicate the above to the next Docs Community meeting.
28+
29+
Where are we with the action items from March 11?
30+
1. Look at front page of docs.p.o and decide which ones should be more prominent
31+
2. Come up with a short: (3 page) tutorial. Carol will start an outline.
32+
3. Document our philosophy, explain the different target users and where they can find the docs they need.
33+
34+
35+
## Agenda
36+
37+
1. What action items are we taking from the discussion at the docs dinner?
38+
* Notes on contributing to docs:
39+
- Melanie’s notes: [Python Docs Contributing Adventure](https://docs.google.com/document/d/11zxisx5XfYOsrDOn4qd-XUSpDltIOi35qiOO9fDLfnI/edit#heading=h.1hkck4lqac8)
40+
- Shauna’s notes: [Python Docs Onboarding Notes](https://docs.google.com/document/d/1icjPpmEUH0BRPDwl7oXLkpasvwZoS5io2LyTEhblku0/edit)
41+
- Notes after discussion with Eric Matthes: [Guiding Principles for Documentation Editorial Board.md](https://drive.google.com/file/d/1elKNdRPTIoNe6EZ4TbS9aquM-RaNDgmc/view?usp=drive_link)
42+
- Sprint ideas from Carol's discussion: [Doc ideas.md](https://drive.google.com/file/d/17uGzCmFnUDBYGwsR9xmzEOGi4fOOSnOj/view?usp=drive_link)
43+
44+
* Other notes from dinner:
45+
- Should you learn Python
46+
- Cheatsheet for rST markup
47+
- Ned says: "Write how-tos for Trey"
48+
- Trey = priorities
49+
- Docs are shared resource
50+
- Add "Did you find this helpful"
51+
- Update "How to contribute to docs" in dev guide and perhaps in a more user friendly way
52+
- What to expect after a docs PR
53+
- Codespell run once by core devs then add to CI after
54+
- Message on PR template for docs that sets expectations for PR review
55+
56+
* Action item: no clear path for contributing to CPython Docs. Devguide section is lacking, mostly for CPython code changes.
57+
* New action item: the PDEB should write tickets for the action items on this meeting
58+
* Decision:
59+
- We are sticking with Rst for CPython docs.
60+
- Myst Parser: https://myst-parser.readthedocs.io/en/latest/
61+
- Mariatta has a talk: [Introduction to Sphinx Docs and reStructuredText](https://www.youtube.com/watch?v=v4eoYpCON_c) - Pyninsula #28
62+
* Action item:
63+
- Ned will write up an outline for “How to contribute to CPython Docs”
64+
65+
2. What action items are we taking from the docs summit?
66+
none
67+
68+
3. Do we have action items from the Docs Community?
69+
70+
71+
4. Is it time for us to focus on filling out these two docs so we can set a direction? Is there something else we should do first because it is either a higher priority or a prerequisite? Are there people in the Python community who have more formal experience with user research and might want to help?
72+
* Discovery doc about learners (Carol, would you like to capture your thoughts in this doc since you seem to have considered the issue deeply?) The Guiding Principles for Documentation Editorial Board.md captures the 3 user personas.
73+
* Discovery doc about contributors (Ned, would you like to capture your observations about the community in this doc since you seem to be the most involved with them?)
74+
* Action item: finish up the 🔒 [Guiding Principles](https://docs.google.com/document/d/1ILusuBaAoxUzm1NDOuiS3sZYePDVB5YcY7RoLkXyfI0/edit?usp=sharing) doc, and officially adopt it. To become the first page of the Docs Guide. To answer the “Discover Doc about Learners” Discovery Doc: Who is Our Learner
75+
76+
5. Todo: form a WG to address packaging users docs
77+
78+
6. Discussing the [Guiding Principles](https://drive.google.com/file/d/1elKNdRPTIoNe6EZ4TbS9aquM-RaNDgmc/view?usp=sharing)
79+
* How to ensure the novices are properly supported?
80+
* Action item: Develop a user-journey. Tutorials, to be added outside of the actual Tutorials section. Eg including examples in references.
81+
* Who are our contributors?
82+
- Core devs. Code changes -> doc changes
83+
- Long-term docs contributors
84+
- Drive-by contributors
85+
- Translations
86+
* People writing dev docs professionally don’t wanna contribute to Open source docs?
87+
* Educators may have feedback too
88+
* As PDEb we can create a system to unblock contributors. Which type of contributors we want to focus on? #2: long-term docs contributors.
89+
* Action item: the doc outline. Share tools/cheatsheet of learning Sphinx/rst, etc
90+
- Note: the logistics of splitting up docs sections will be a big project
91+
* Action item:
92+
- Pull out docs-related from devguide as a (git) subtree
93+
* There are a lot of undocumented Docs tooling. Should write it up?
94+
95+
7. Next meeting: vacations, EuroPython.
96+
* Cancel July, and meet August 12.

‎updates/2024-08-12-editorial-board-update.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Meeting Notes: Python Docs Editorial Board
2+
3+
## August 12, 2024
4+
5+
## Attendees
6+
7+
Mariatta, Ned
8+
9+
10+
## Old Action Items
11+
12+
Where are we with the action items from June 3?
13+
- [Create a dir in the GitHub repo and move there?](https://github.com/python/editorial-board/issues/5) Move or link the docs to the GitHub repo? Communicate this at the next Docs Community meeting
14+
- DONE: Ned will write up an outline for [“How to contribute to CPython Docs”](https://github.com/python/editorial-board/issues/4)
15+
- [Finish up the Guiding Principles doc](https://github.com/python/editorial-board/issues/10), and officially adopt it. To become the first page of the Docs Guide
16+
- [Form a WG to address packaging users docs](https://github.com/python/editorial-board/issues/11)
17+
18+
19+
20+
## Agenda
21+
22+
1. What should we accomplish before our next call?
23+
2. Migrate documents from Google Drive to GitHub?
24+
3. Next steps for docs guide?
25+
4. Next steps for Guiding Principles doc?
26+
5. Next steps for wg to address packaging user docs?
27+
28+
## Notes
29+
30+
We did not go through the planned agenda, but Mariatta and Ned discussed the new outline for DevGuide.
31+
32+
### New outline for devguide / contribution guide
33+
34+
Proposed outline for combined guide: https://docs.google.com/document/d/1Ajk_Vj3rccJ9ReB7WCNhEnLHQP23iMg7jAFQ-CYKzWo/edit
35+
36+
#### Next steps:
37+
38+
- Create devguide project
39+
40+
- Write devguide issues
41+
* Overall restructure, with placeholder sections, according to the Google Doc. No need to write content. Placeholder pages can include bullets about the topics to be covered there. Placeholder pages can have a boilerplate info box explaining that the page is in-progress.
42+
* Write issues for each section that needs to be fleshed out.
43+
44+
- Question: We propose to publish the new-organization skeleton as the devguide while we flesh it out. Ask in PDEB Discord if anyone objects. We want to keep it simple, so no branch, publish the placeholders
45+
* It will be for a short time
46+
* Don’t want to maintain a long-lived branch
47+
* Raises the visibility of the work
48+
* Encourages contribution
49+
- Set a target date for when this is done
50+
* Aim to have it done by May 2025 for PyCon US
51+
* Maybe a sprint at PyCon to get it over the line

0 commit comments

Comments
 (0)