You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As a new contributor I'm at a stage where I have the interest to both report and work on an issue. As with all of us who have "real life" obligations, my time is limited. So when I find issues in docs (or other projects) I'd like to know if this pattern is acceptable:
Create a report.
Get confirmation that it's valid through some discussion.
Get assigned to the ticket.
(Here's the topic of this question) Take the time I need to work on the problem.
Submit suggestions for resolution.
Work with the team to refine the suggestions, and ultimately get the issue resolved.
On that point 4 : Consider a documentation page that's seriously out of date, requiring a lot of refinement. It takes time to read the code, experiment with it, learn the nuances, articulate what's been learned, verifiy the accuracy of the new understanding and the new language that describes it, and finally to present that in the ticket in a format that can be discussed and refined. That process might take a couple months to play out.
I don't think it's good for anyone to hold onto a challenge like that, not even reporting an issue until a resolution can be articulated. And yet we don't want steps 1,2,3 above, that remain in permanent limbo after someone loses interest.
So I'd like to know how this team would prefer a scenario like that to play out. I think it would be appropriate for anyone assigned to a ticket to periodically indicate their continued interest. This could include "still working on it", "not working it right now but still interested", or "can't work on it in a 'reasonable' time frame".
We could suggest that the Issue/ticket be used as a temporary repository for work-in-progress refinements. That would not only reaffirm that an issue is being processed but it will get more eyes on the evolving resolution.
But I don't think that's always a good approach, because sometimes as our knowledge on a topic evolves, our approach to describing how it works can change radically. It doesn't makes sense to get other people involved on something that could be completely scrapped after some "aha" moment. It might make more sense for a contributor to fork the doc repo, work on it in their own space as it evolves, and then they can PR a proposal back here for a merge. That works with software, why not with docs? See #256 on this topic.
This question can be applied to any repo, any team, including WP Core. What's a 'reasonable' time to wait for someone to complete a task after assignment? Should "are you still working on this pings be automated? Should there be automatic unassignment after some number of months of inactivity on a specific ticket by a specific individual?
Here are just a couple short examples of these documentation challenges, without pointing to specific doc pages:
I frequently find blogs or StackOverflow posts that criticize these docs for being incomplete or inaccurate. I'd like to reply to the authors "you're right, I've just created a ticket on that, let's fix it".
In my own development where I need to deeply understand details of the WP lifecycle, I am puzzled about how specific hooks work. The docs are minimal, there are no code samples, I need to spend hours to days hunting for examples and doing my own experimentation. I'd like to go through 1,2,3 and then have some time to get through 4 ... or at least go through 1 and 2 and allow someone else the opportunity to contribute.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
As a new contributor I'm at a stage where I have the interest to both report and work on an issue. As with all of us who have "real life" obligations, my time is limited. So when I find issues in docs (or other projects) I'd like to know if this pattern is acceptable:
On that point 4 : Consider a documentation page that's seriously out of date, requiring a lot of refinement. It takes time to read the code, experiment with it, learn the nuances, articulate what's been learned, verifiy the accuracy of the new understanding and the new language that describes it, and finally to present that in the ticket in a format that can be discussed and refined. That process might take a couple months to play out.
I don't think it's good for anyone to hold onto a challenge like that, not even reporting an issue until a resolution can be articulated. And yet we don't want steps 1,2,3 above, that remain in permanent limbo after someone loses interest.
So I'd like to know how this team would prefer a scenario like that to play out. I think it would be appropriate for anyone assigned to a ticket to periodically indicate their continued interest. This could include "still working on it", "not working it right now but still interested", or "can't work on it in a 'reasonable' time frame".
We could suggest that the Issue/ticket be used as a temporary repository for work-in-progress refinements. That would not only reaffirm that an issue is being processed but it will get more eyes on the evolving resolution.
But I don't think that's always a good approach, because sometimes as our knowledge on a topic evolves, our approach to describing how it works can change radically. It doesn't makes sense to get other people involved on something that could be completely scrapped after some "aha" moment. It might make more sense for a contributor to fork the doc repo, work on it in their own space as it evolves, and then they can PR a proposal back here for a merge. That works with software, why not with docs? See #256 on this topic.
This question can be applied to any repo, any team, including WP Core. What's a 'reasonable' time to wait for someone to complete a task after assignment? Should "are you still working on this pings be automated? Should there be automatic unassignment after some number of months of inactivity on a specific ticket by a specific individual?
Here are just a couple short examples of these documentation challenges, without pointing to specific doc pages:
Thanks for your interest.
Beta Was this translation helpful? Give feedback.
All reactions