blog post: "Five (?) simple rules for writing awesome bug reports (you won't believe #3)"

[orbeckst]

Following up on the discussion in PR MDAnalysis/mdanalysis#1967 we might want to write our own short post on what we would people like to consider when submitting bug reports for MDAnalysis.

• issue tracker is for bugs, enhancements, API decisions
• mailing lists are for general "How do I...?" and "What is ...?" questions

The issue template already does a good job focusing on the key things.

If any of the @MDAnalysis/coredevs has opinions on the matter, please discuss them in this issue.

[orbeckst]

(Originally MDAnalysis/mdanalysis#1967 (comment)) I quite like Simon Tatham's https://www.chiark.greenend.org.uk/~sgtatham/bugs.html (and the related http://www.catb.org/esr/faqs/smart-questions.html by ESR). https://musescore.org/en/handbook/developers-handbook/getting-started/how-write-good-bug-report-step-step-instructions is also good.

Maybe we can distill all of the above into a short read. Short seems important to me because for most people, raising an issue already means overcoming a high activation barrier – especially for the kind of knowledgeable users that might be able to give very good issue reports. Keeping any additional (even optional) reading short is good.

Perhaps we manage to boil it down to five bullet points, along the "Ten simple rules for ....".

[richardjgowers]

So we're buzzfeed now? :)

[kain88-de]

If we make it ten we can write a PLoS One article http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003858

…

On Wed, Jul 4, 2018 at 5:36 PM Richard Gowers ***@***.***> wrote: So we're buzzfeed now? :) — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#81 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEGnVkZP5vXOyre9Cht2SO5r6N_wq0jLks5uDODngaJpZM4VBl6Q> .

[orbeckst]

I was more inspired by PLOS than BuzzFeed ;-). But I had to laugh at the new issue title. 🤣

(Thanks for the link for "10 Rules to write a 10 Rules article" – I hadn't seen that one.)

[orbeckst]

See also "community page" #62

[orbeckst]

See also Alan Grossfield's How to be a good member of a scientific software community https://osf.io/kgr45/

(Somewhat related https://exercism.org/docs/community/being-a-good-community-member because I stumbled over it and liked it.)