Adding initial content for Sprint Guide #609
Conversation
There was a problem hiding this comment.
Apologies for the delay in responding - I've been travelling for work, and wanted to give this the attention it deserves.
tl;dr - this is a great first pass. It's exactly what I had in mind - although there's some long comments/edits, that's more about polishing the content to a fine sheen rather than an indicator of anything fundamentally wrong.
Most of the comments I've left inline are aimed toward the general goal of making the text "bulletproof" as a standalone document. They err on the side of over-explaining, with a view to making sure that the core team needs to provide as little background or context for contributors that are coming in completely green to the process. That said - I've possibly over-corrected. If you think I've pushed too far in the over-explaining, or I've been too wordy (which... is a flaw I know I have in my writing :-) )that's entirely possible, so feel free to push back.
I haven't filled in any of the TODOs yet - my high level impression is "yes, those all look like they need to be TODone 😄". I'm not sure if you were planning to fill those in yourself once the high level structure was sorted, or if you're looking for direct input from me on those. If you want me to take a pass at any of them, I'm happy to do so (although I'll probably wait until I'm back at home next week and I can give them my full attention)
The one other detail I haven't looked at is how this document renders in the parent page. IIRC it's the "summary" section that will be rendered as a description on the "contributing" page; I want to make sure that it "fits" as part of that parent content.
Co-authored-by: Russell Keith-Magee <[email protected]>
I agree entirely with your aim here. I don't think you over-explained anything. I made a couple of minor changes, but I think you pretty much nailed it.
Hah! Yes, they do need to be TODone. The TODOs are the bits we didn't get to in our conversation that you need to get out of your brain. The "Common Questions" could be a group effort, really, but I mean group effort on the part of other Bee Team members. I'm happy to hop on another call next week when you're home again, and discuss things in more detail, if that's more convenient for you than filling things in yourself. However it happens though, the TODOs are yours. I basically took things as far as I could from my notes. You and I agreed on the last call that it made sense to wait on the details until we had this much done. And here we are!
Yes, the summary is what shows up. The current text is absolutely placeholder. At the moment, the link to the page is at the end of the Contributing page, as a header with the page title ("Sprint Guide"), and the summary text below it. If you want it somewhere else on that page location-wise, I will need some help because I don't understand how to make Lektor put a new subpage in the middle of the text content. It's clearly possible, the "First Time Contributors" subpage is first, but I'm unclear on what went into making that happen, even after looking at it and the Contributing page text. If last is fine, than the only thing needed to make it fit properly is updating the summary to something useful. I figured this would be the last thing on the list to do. |
There was a problem hiding this comment.
I've had a chance to do a pretty heavy edit pass - at this point, I think all the TODOs are either Done or deleted; although there's a lot of changes, the first draft you've provided was invaluable.
Highlights of the update:
-
I've removed the "FAQ" section on the basis that I couldn't actually come up with anything that would have fitted in a FAQ better than an explicit section.
-
I've modified the questions so they're framed less as "7 questions each with 5 subquestions", any more in terms of "7 topics for a conversation we want to have about you". It's the conversation that we want to have, not just structured literal answers to a set of questions; my hope is that giving some background to why were asking might shake out some deeper answers, without needing to have a longer in-person script.
-
I've added some extra content providing an introduction to sprints (since that has historically been a point of confusion), links to contributions guides, "post contribution" workflow, and a few points doubling down on the "no dumb questions", "anti-imposter syndrome" stuff. The contribution guide links won't all be live yet - writing that section pointed out some inconsistencies that I'm working on upstream.
-
I've modified the content "situating" the sprints page. There are shortcodes so
beeware.org/b/sprintswill link to the sprint page; and the contributing page links to sprints as a special topic in the sidebar.
I'd appreciate any thoughts (and corrections!) - if I pointed you at this document as a first-timer, would I scare you off?
|
Apologies for the delayed response - I spoke at a conference last weekend, and that took up most of my time leading up to it. I'm preparing for PyCon now, and this is one of my priorities. I read through it and I have some ideas, but before I get into that, I wanted to make sure you knew I was getting back to this.
Thank you! This is exactly the process I was expecting heading into this; I laid out everything we discussed, with the intention that you would fill in the rest of the details as you had them in your head.
You were vague on this when we talked about it, so removing it makes sense. I included it because you brought it up, but I think it'll be covered in getting folks set up. I will say, we had talked about going through Discord and the Core Team's brains, finding out what sorts of things are being asked-and-answered repeatedly, and documenting those. I still believe this would be valuable, however I think that giving this concept its own home makes more sense.
This makes a lot of sense. I think there are some changes that could be made here, but overall the structure is much more useful.
This is also good. I see a couple of minor changes that could be made, but again, this is a great change overall.
This was entirely up to you, so I'll defer. I don't know if your intention is still to have a huge QR code poster to point to, but if it is, the page's location on the website is far less important than the link directly to the page. Out of curiosity, what is the
There are genuinely some things in this page that would probably make me nervous as a first-timer. But, that's the point of this discussion! I will do an in-line review with my thoughts and suggestions. Thanks again for the latest update! |
There was a problem hiding this comment.
@freakboy3742 Alright, here are my suggested changes. Let me know what you think!
| gutter: | ||
|
|
||
| The Bee Team is always available to answer questions. If you're in doubt... ask! | ||
| There's no such thing as a "stupid question" - if you're confused, it's because |
There was a problem hiding this comment.
| There's no such thing as a "stupid question" - if you're confused, it's because | |
| There's no such thing as a "bad question" - if you're confused, it's because |
"Stupid" has some unintended connotations that are worth avoiding.
There was a problem hiding this comment.
I know there's connotations around "dumb" (convolving "non-verbal" as "non-intelligent") and "idiot" (as a historically "medical" term with unpleasant implications in treatment) - am I missing one around "stupid"?
Assuming that there isn't a clinical/etymological issue that I'm missing - my understanding is "stupid" is the actual connotation we're looking to combat here. "Sorry for the stupid question" is literally the thing that gets asked (not always with the word "stupid", but the intention is the same). Directly saying "no really, that isn't a problem" seemed positive I this context.
(And, as a mild counter: there are bad questions - sea-lion questions, for example).
I'm not disagreeing that there might be room to improve how we're expressing this - I just want to make sure I understand what it is that we're trying to avoid saying (and why) - if only because I may need to take "no such thing as a stupid question" out of my lexicon...
There was a problem hiding this comment.
Evidently, it depends on where you look, but it is my understanding that "stupid" is also ableist. There could also be a difference in consideration between Australia and the US.
Below are a few resources that mention it, however not all resources on ableist language include it. These resources are not "official" in any way (other than one being a study, but that doesn't make it official), and therefore are likely the opinion of the author. As not all resources include it, there is obviously not a consensus within the disabled community on whether it should be considered ableist. My reasoning behind changing it is that if any part of the community considers it to be ableist, then it may be worth avoiding.
This is a study on the usage of ableist language that includes "stupid" in their list of words.
This and this are general posts that include it.
I understand your take on it, in terms of considering it a positive. And, I understand that the phrase speaks to the question being asked, not the individual asking it. However, it's the word itself that is triggering, so even in a "positive" usage can bring up the negative feelings potentially associated. I realise this was not your intention, and that "no stupid questions" is a oft used phrase. I am by no means insisting that you replace it, but in general, simply because something is commonly used should not be a justification for continuing to use it.
All of that said, this is your decision, and we'll go with whatever you consider to be the best option. I get your justification for including it. My comments above are meant only to provide an explanation for my suggested change, not to insist on you accepting the change. I was deliberately vague in my initial comment, because I did not want to come across as accusatory. So, asking for an explanation is completely reasonable.
In the event that you choose to replace it, "bad" may be an unacceptable replacement, as I do agree there are bad questions. Unfortunately, I don't have a good answer other than rewording it.
There was a problem hiding this comment.
Thanks for the clarification.
It sounds like the best option here is to reword the statement. How about:
The Bee Team is always available to answer questions. If you're in doubt... ask! Don't be afraid to ask any question. If you're stuck, we want to get you unstuck. If you're confused, it's because the topic is complicated, and we haven't explained it well enough.
?
Co-authored-by: Kattni <[email protected]>
No problem at all - thanks for circling back with those updates - almost all of them are completely uncontroversial and understandable improvements.
Completely agreed - sounds like a good project to have running in the background at the sprints.
The intention is still to have a printed poster (don't know how huge it will be... but big enough to see and scan, anyway); but given the page can be found on the website without the QR code, it seemed useful to have some content for people that found the page organically.
It's a namespace. There's no actual content under the
Hopefully these have all been addressed by your suggested edits; if there's any bigger-picture issues, let me know. The one outstanding discussion point is around the "stupid" questions thing - to be clear, on that one, I'm mostly trying to make sure I haven't missed some context or sensitivity training somewhere. I'm aware that "stupid" can be a triggering word; in this case, my thought was that even though we're using the word, the word itself is being dismissed, so it wouldn't be a problem (or, at least, it's being presented in a "this is a thing that doesn't exist" context). However, if I've misread that, or there's a bigger picture thing that I missing, let me know. |
|
I've never replied to a PR via email, so here's hoping this works.
That is an excellent rewording of it.
Let me know if there's anything else needed. Otherwise, I think this is
good to go.
…On Sun, May 4, 2025, 20:45 Russell Keith-Magee ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In content/contributing/sprint-guide/contents.lr
<#609 (comment)>
:
> +Congratulations - you've contributed to BeeWare! If this is your very first
+BeeWar contribution, you've also earned your `BeeWare Challenge Coin
+</contributing/challenge-coins>`__ - find a member of the core team, and they
+will give you a coin!
+
+Help! I'm stuck!
+-----------------
+
+If you get stuck at any point along the way, find a member of the Bee Team and
+ask. We're eager to help - and we want to make sure you have a successful sprint.
+
+---
+gutter:
+
+The Bee Team is always available to answer questions. If you're in doubt... ask!
+There's no such thing as a "stupid question" - if you're confused, it's because
Thanks for the clarification.
It sounds like the best option here is to reword the statement. How about:
The Bee Team is always available to answer questions. If you're in
doubt... ask! Don't be afraid to ask *any* question. If you're stuck, we
want to get you unstuck. If you're confused, it's because the topic is
complicated, and we haven't explained it well enough.
?
—
Reply to this email directly, view it on GitHub
<#609 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AB4AGATSJ7WZAF3WOQLW23L242YCJAVCNFSM6AAAAAB2UJF4A6VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDQMJTGY2DQMRXHE>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
There was a problem hiding this comment.
I've never replied to a PR via email, so here's hoping this works. That is an excellent rewording of it. Let me know if there's anything else needed. Otherwise, I think this is good to go.
Awesome - thanks for the initial PR, and for all the feedback on my additions!
This page is intended to assist with guiding folks through the initial steps of joining the BeeWare sprints. The idea is to limit the amount of repeated instruction to folks who are joining for the first time, and hopefully provide a better experience for sprinters and the BeeWare folks alike.
Obviously the layout may not be what @freakboy3742 had in mind, so I'm submitting it as is for feedback.
At the moment, there are a number of TODOs on the page. I went through the basics with @freakboy3742, and the current content includes everything we discussed (or at least everything I managed to get into my notes). I'm happy to have another call to begin filling in the rest, or I'm also happy to hand it over at any time.
PR Checklist: