Documentation community meeting: April 4th

Hello,
Another Docs meeting will be held this Monday on Discord. (If you’re not there yet, please join at discord.com with sMWqvzXvde, ideally a few hours before the meeting. Contact me if you have trouble with that.)
If you want a calendar invitation, Mariatta’s handing those out on Discord.

On the last meeting we decided to have the meeting at the same time, but due to daylight savings, “same time” is ambiguous. “same time” in UTC, but the calendar event is “same time” for people who switched to summer time.
If no one speaks up, we’ll meet according to the calendar event, 21:00 UTC, one hour earlier than some previous notes/announcements said.

3 Likes

By my calculations that is

  • 2 pm San Francisco
  • 5 pm New York
  • 22:00 London
  • 23:00 Amsterdam
2 Likes

Please forgive this if my question is just ignorant, but, for those of us who find Discord difficult to navigate… is there a specific #channel this will be happening in?

My guess is here (that’s the general channel for this group, and that’s where the timing has been discussed). You may have to click on the “event” in the top left of the UI though.

Which shows me the message:


NO TEXT CHANNELS

You find yourself in a strange place. You don’t have access to any text channels, or there are none in this server.


There’s no “Event” displayed in the UI. The mystery that is Discord remains.

Nice.

I don’t see you joined. When you go to Discord, click the + in the left bar:
image

And there, select Join server and put in sMWqvzXvde.

1 Like

Thanks! I think I’m there now.

Reading the notes now (couldn’t make it in real time). Too bad you all discussed the typing peps/docs situation without anyone from that community present. We’re well aware of it. I’m not sure we need your help, TBH. In any case I recommend writing to typing-sig before putting more effort in this.

I had invited @Jelle to the Discord and mentioned him as being a good person to talk to about it, as per my previous discussions with him on the topic, he already had a similar idea in mind and the typing community had been discussing it, which I shared after the broader issue (encompassing more than just typing) was raised at the meeting. The main action item, as I recall was to reach out to Typing-SIG about the issue, but I’m not sure what was actually done yet on that front.

Based on what I’d gathered from Jelle, it seemed (as in the packaging community) one of the main limitations in realizing it was simply limited time and resources to make such a significant transition, at least on a shorter timeline. If things have moved along substantially since then, as seems to be implied above, then that’s great to hear.

Nobody’s reached out yet. I can think of a few other folks on typing-sig who’d be interested (e.g. Sebastian Rittau).

And no, we haven’t solved the time and resources issue. Neither has the docs WG it seems. :slight_smile:

PS. I seem to have misplaced the doc with the notes, and neither this thread nor the Discord channel seems to have a handly link.

Indeed, I had to go digging for it myself in the Discourse Events at meeting time, and it seems that was deleted or otherwise no longer exists, but fortunately since I edited it, I happened to have it in my HackMD account history. Here’s a link a link to the HackMD, and it was just now opened as python/docs-community#47.

If we can remember to link that directly in the future, it would be much appreciated (unless there’s some reason not to) :wink:

I’d like to second Guido’s frustration at not knowing that typing documentation would be discussed at this meeting – I would have been interested in attending, had I known. I only found out that it had been discussed by randomly scrolling through discuss.python.org topics just now, and seeing this discussion. I’m sure this was merely an accidental oversight, but it’s something to bear in mind for next time :slight_smile:

I have just submitted a detailed proposal for a possible way forward here: Proposal: Convert the `typing`-module PEPs into a series of HOWTOs · Issue #91533 · python/cpython · GitHub. Feedback welcome.

Hi,
Well, we didn’t really discuss in much detail – for this particular topic the notes are rather complete. The GH issue Alex just linked covers much more than was discussed at the docs meeting.
There was the idea that docs team could help out, but due to the mentioned time and resources issue, there’s nothing to report.

1 Like

My frustration was actually about something different. Reading the notes I get the feeling that the participants are a bit much into the work of being an organization and not enough into actually documenting stuff. Do I mis-perceive that?

2 Likes

(I should probably add that this reminds me of an old event. Around 1995 some folks wanted to create a “Python Software Association”. Paul Everitt will remember those days. There was a lot of talk about bylaws and membership models and such, and in the end nothing happened for many years. It took until 2001 for the PSF to be founded, using a very different approach.)

I think it is fair to say that we are still finding our feet, including distinguishing between the working group proper and the community of documentarians, how to encourage and track work, etc.

2 Likes

That’s actually my impression of the Docs WG – i.e. the PSF Workgroup with formal membership, charter, and voting. As I understand, this group got bogged down in discussing how to add new members, and never submitted its charter to the PSF, so it doesn’t actually exist yet.

It took me some time to realize that this group is not what I want to contribute to. You might have noticed a lot of things were rebranded to Docs Community – an informal group similar to e.g. Typing-SIG.
The Docs WG is basically in the same place it was a year ago: anyone’s free to pick it up, but there’s no champion driving it forward right now.
It took a bit of time to clear this up, but hopefully most people involved are on the same page now.

Now, for the meeting notes: there’s a bit of an issue with re-using the same document for a rolling agenda and the meeting minutes. It usually works OK, but needs some upkeep, and for this meeting I was ill and didn’t prepare as well as I could. I hope to do better next time.
So, the notes are a a very bad indicator of how much we talked about a topic, and some notes we skipped entirely.
Specifically, the “Structuring” section is mostly discussion added before the meeting.

Oh, thanks for that clarification. I had no idea that this was a separate initiative. Too bad about the Docs WG. I do hope this group will be more successful!

1 Like

Lucky you; I’m getting more and more confused :smile: I do wish both groups success, though.

I think this calls for a Life of Brian quote…

Reg: “We’re the People’s Front of Judea!”
Stan: “Oh. I thought we were the Popular Front.”
Reg: “People’s Front!”
Francis: “Whatever happened to the Popular Front, Reg?”
Reg: “He’s over there.” [points to a lone man]
Reg, Stan, Francis, Judith: “SPLITTER!”

1 Like

Let me try and clear things up (for my self):

  • IIUC, the active group is now the Docs Community
  • The Docs Community group started out as the Docs WG (here)
  • The three available meeting notes seems to mention both groups; I find that confusing :slight_smile:
    1. Feb 2022 meeting notes: I get the impression that this is the Docs WG [1]
    2. Mar 2022 meeting notes: I get the impression that there are now two groups; looking at the notes, I get the impression that the two groups are somehow connected
    3. Apr 2022 meeting notes: ditto – I’m still confused :slight_smile:
  • https://docs-community.readthedocs.io mention both groups; looking at the Purpose and Common Goals of the Docs WG, it seems that some of those goals overlap with the Docs Community activities (ref. Diataxis discussion). Observation: The Docs Community does not have a Purpose and Common Goals section. I find this confusing :slight_smile:
  • The “team” section lists the members of the two teams. According to that page, all “current active doc group” members are members of the Docs WG (“Workgroup Members”) and that the members of the Docs Community (“Community Team”) are to be decided. This seems to contradict Petr’s latest post. Or the other way around :slight_smile: I’m genuinely confused, but very happy for the efforts! I’m also fine with being left in a confused state, as long as the docs end up being improved :rocket:

Maybe it’s just a matter of updating the docs-community RTD site.

Suggestions for improvement:

  • Clearly describe the purpose and goals of each group
  • Clearly describe the relationship between the two groups
  • Update the member list in the docs-community “team” section

  1. “We talked about the docs group at the last 2 lang summits. This time the group has started!” ↩︎

1 Like