What's a good way of raising small suggestions or pointing out minor mistakes?

Sometimes when reading documentation I think I see ways that things could possibly be better explained to newbies to programming and Bokeh like me. You guys have been incredibly helpful to me and it’d be nice to correct others on the internet contribute something in return in a way others don’t find annoying or disrespectful. I also don’t want to kick up a big fuss about something or posit some grandiose idea to only learn I’m a nitpicking dumbass who misunderstood something or didn’t consider there was already a good reason why something was the way it is.

For example, I was reading the guide on tabs and I wanted to see the list of tab arguments, but I couldn’t find a link on that guide. So I had to search for tabs to eventually find this documentation page instead. My suggestion would be to provide a link to that part of the documentation in the guide, or if it already exists make it more apparent. Or maybe fix minor typos, dead links, or maybe provide examples to things. That kinda stuff.

Is there anywhere we can raise these kinds of small ideas?

You can submit these kinds of documentation update requests via GitHub issues (https://github.com/bokeh/bokeh/issues), which then become great low-hanging fruit for any interested first contributors (including yourself!). :slight_smile:

2 Likes

Cool! Are you sure stupid or pedantic suggestions will be welcomed in an area for “update requests” which lists “issues”? I made this Github issue at @Bryan’s request the other day and I felt awkward giving it the misnomer of a “bug” because I didn’t know what else to classify it as.

I could easily make more suggestions on Github but as a good proportion of them will be stupid or at least unsuitable I expect that’d quickly come to the offense or annoyance of others, so I don’t think that’d be constructive. Maybe we could use some kind of new category like ‘tentative and probably idiotic suggestion’?

While I understand the feelings of doubt and hesitation behind the question, I think designating (and pre-designating, and self-designating) some questions or suggestions as less worthwhile than others would absolutely be counterproductive to maintaining a friendly, supportive development community that is welcoming and respectful to new contributors. I would add that if at any time you feel that community standards are slipping in this area, you should feel free to let us know.

Your bug report looks fine! I agree though that sometimes when putting in an issue, the bug vs feature dichotomy can feel strange. “Well, it’s not TECHNICALLY broken…” The nice thing is, the project maintainers will look at your issue, and add labels or other tweaks anyway. We look forward to your suggestions, especially around documentation-- that’s an area in particular that I’m keen on improving.

I second everything @carolyn has said and would add only some context in case it is useful: There is a “task” label that we can and do often re-classify issues with. The reason the tracker input only lists “Bug” and “Feature” as options is because we want to discourage folks from seeking general help/support on the tracker (they should come here for that!) and so far limiting the options seems to be the best way to do that. But the tracker is the right place for anything that “needs to be done” no matter how big or small, so that it can recorded and not forgotten, and also be prioritized along with everything else.

1 Like