[elliekelly]

Are there any good articles on writing helpful bug reports? Whenever I submit a bug I try to give as much detail and be as specific as possible but I always imagine some dev somewhere reading it rolling their eyes at the unnecessary paragraphs I’ve submitted.

[ArloL]

I can recommend https://www.chiark.greenend.org.uk/~sgtatham/bugs.html

[kens]

It's interesting to compare that guide "How to report bugs effectively with ESR's "How to ask questions the smart way" [1]. They both cover similar material, but the styles are extremely different. The latter is rather hostile to the reader: "If ... then you are one of the idiots we are talking about." "If you decide to come to us for help, you don't want to be one of the losers." It's also heavy on "us vs them", how we are experts and you need to treat us properly.

You know, it just occurred to me that the "How to ask questions" document is targeted as much at hackers and how they should maintain their "standards" than at users who are asking questions. For example, the document has approving examples of "logically impeccable but dismissive" hacker answers; these make more sense as instructions on how a hacker should respond than as something relevant to a user.

I guess my point is that I had read the "How to ask questions" document for decades and viewed it as an objective document, not realizing how arrogant and "gatekeeping" it is.

[1] http://www.catb.org/~esr/faqs/smart-questions.html

[_dain_]

I agree, that "how to ask questions the smart way" article always left a bad taste in my mouth. Perhaps there should be a "how to answer questions" companion piece.

[LambdaComplex]

esr seems to have a pretty big ego, just based on his writings. (e.g. at one point he declared that he can tell if someone is smart or not just by looking at them)

[fao_]

He actually at one point wrote that he was a reincarnation of the god Pan, so he has/had a very literal god complex, too. It's such a shame that he was the person to interpret hacker culture for those of us in the future, because he's hardly a good lens

[setpatchaddress]

I don’t disagree with your sentiment, but that wasn’t meant as a literal “I am the god Pan” — it was figurative, hyperbole. At least, that’s my recollection from when I read it a couple of decades ago.

[B1FF_PSUVM]

Strange, he's old enough to have watched the first TV run of Lt. Columbo ...

[jodrellblank]

The https://WhatHaveYouTried.com guy backtracked after a few years in the linked follow-up article, ashamed of giving the geek world another way to gatekeep and tell unworthy people to get lost.

[bmn__]

Gemmell made a mistake in assuming the shame and guilt of the people who abused his article. The article is just a tool. We should hold the abusers responsible for their gatekeeping and telling others to get lost.

[elliekelly]

Thank you! I’m definitely guilty of mongoose-ing and diagnosing in my bug reports so this is very helpful!

[jraph]

> diagnosing in my bug reports

It's probably fine, if you put it in a separate section, clearing indicating that you are guessing.

At work we have an optional "diagnostic" section in our ticket template, mainly intended for the team, but I'd be happy to see a user try to fill it. At worse it's harmless, at best it gives the actual reason, somewhere in the middle it can give ideas even if it is wrong.

[krisoft]

> At worse it's harmless

I wish. It happens very often that such speculation derails the whole investigation. It really shouldn’t, but people are people. If the title of the bug report says that the foobar is broken it might take weeks until someone realises that they were wrong and actually the problem is in the frobnicator which feeds the foobar.

Especially when because of this we assing the investigation to the wrong team. The foobar people don’t want to appear as if they don’t take the bug seriously, but all they check everything looks normal on their side.

[bedobi]

As a dev, I think

STEPS TO REPRODUCE Open foo click bar

EXPECTED RESULT saves bar

ACTUAL RESULT crashes with error x912344

MISC <any other logs, details here>

is the best. It gives just the right amount of detail to get started, in a good, actionable format.

[rnotaro]

Yeah, that was basically most of the bug template we were filling when I used to work QA at Warner Bros. Games.

    Summary :
    Steps to reproduce :
    Expected result :
    Actual result : 
    Build/Version :
    And a few more fields about platform, severity, etc. on Jira.

[bedobi]

Lucky you to have that standard enforced within the org! We don't so I pretty much invariably have to respond to "bug reports" ("foo doesn't work pls help") with "can you please format your bug report like this?" haha

Out of curiosity, what does deving for Warner Bros mean? Like working on their internal systems and stuff? Netflix integrations or something? Sounds cool, bet you get to see movies before they come out too!

[rnotaro]

Sorry for the delay!

I was working at their Montreal Studio. It's exclusively a video game studio. I was mostly working in QA on Middle-earth: Shadow of War.

Even if the game is technically developed by Monolith Productions, Warner Bros. Interactive Entertainment (WBIE) helps with their ressources (Artists, QA, Devs).

There's also alot of internal tooling for Builds automation, Automated testing / QA Aids tools, etc that is handled by WBIE as the game editor.

We didn't see movies before they got out but we had access to a 30-50 persons theater room that I was able to "rent" for free outside of business hours to watch movies with friends and show them the non-secure areas of the office. (Cafeteria (Free drinks!), gaming room, etc.))

I'm not really into commics but we had a room with thousands of comic books that we could take and read anytime we wanted (WB owns DC Entertainment).

I worked there 6-8 months when I was out of school before getting my first dev job.

[bedobi]

No sweat, I'm glad to see the reply at all :) those perks do indeed sound really cool haha

[hyperman1]

Very important to also ask: Which application. Get an URL if at all possible. If someone says 'the calendar program is down', I have at least 5 candidates, and 50/50 chance something I've never seen pops up.

Users tend to rename programs, even give them names of other programs. Our entire finance department can't wrap their heads around the fact that 'Oracle' is not a bookkeeping application. Worse, they are now convinced the new version is called 'fusion'. Oracle financials? Never heard of.

[drdrey]

Use this template:

1. When I do this

2. Here is what I expect to happen

3. But instead, this happens

[bentcorner]

One more tidbit: In the "When I do this", I find it useful to omit stuff that isn't interesting. Does the thing fail if I do something immediately? Or does it only occur if the application has been dormant for a few minutes? Does it only occur using the mouse, or can I use the keyboard?

Get a good set of steps for reproducing the problem, but wander a little off those steps to see what is actually necessary. I've been surprised more than once when something that I thought was incredibly complex only required a few steps. And also been surprised when a complex repro was actually complex (e.g., if I drag quickly it works, but if I drag slowly it doesn't? what?).

[account42]

It's probably better to err on the side of having too many steps rather than missing cruicial steps to reproduce the problem.

[dotancohen]

...4. And this is my software version and Linux distro.

[input_sh]

Also useful to run the app from the terminal, replicate the bug, and see if any logs pop up.

[toomanybeersies]

Ugh no thanks, I'll just send them a screenshot and say "it's broken, please fix this!"

If it's good enough for my colleagues to submit tickets like this, it's good enough for me!

[westurner]

From "Post-surgical deaths in Scotland drop by a third, attributed to a checklist" https://westurner.github.io/hnlog/#comment-19684376 https://news.ycombinator.com/item?id=19686470 :

> GitHub and GitLab support task checklists in Markdown and also project boards [...]

> GitHub and GitLab support (multiple) Issue and Pull Request templates:

> Default: /.github/ISSUE_TEMPLATE.md || Configure in web interface

> /.github/ISSUE_TEMPLATE/Name.md || /.gitlab/issue_templates/Name.md

> Default: /.github/PULL_REQUEST_TEMPLATE.md || Configure in web interface

> /.github/PULL_REQUEST_TEMPLATE/Name.md || /.gitlab/merge_request_templates/Name.md

> There are template templates in awesome-github-templates [1] and checklist template templates in github-issue-templates [2].

> [1] https://github.com/devspace/awesome-github-templates

> [2] https://github.com/stevemao/github-issue-templates

[ognarb]

https://community.kde.org/Get_Involved/Issue_Reporting This one is pretty good

[skeeter2020]

bug reports and communication in general: If you've got a good summary/abstract more detail is always better. I don't know if I've ever had to talk to someone on my team about how they "over communicated" (not the same as TMI!). Make the receiver responsible for saying "OK, that's enough, got it!"

[edflsafoiewq]

Conversely I think you should generally write the smallest amount of text you can. It maximizes the chance someone else will actually read it.

[codetrotter]

I sometimes try to follow the journalistic reporting way of writing. (Not the clickbait style mind you.)

So I start it off with a few brief paragraphs of text explaining what I did, what happened and what I expected to happen. Each paragraph only a couple of sentences long.

Then below that I fill in with more details.

Of course this still means that if you glance at it you still see a lot of text and may not bother reading. But my hope is that if by chance the recipient does read the first few paragraphs then it will provide the necessary motivation to either read on or to begin investigating on their own.

[stjohnswarts]

It's best to do something like

1. config and versions

2. the bug (failure to see expected results

3. how to reproduce in as simple terms as possible

4. any data such as screen shots, core dumps, logs, etc

[dylan604]

Think about what you would want to know if someone was reporting the bug to you. Provide at least that much information.

[WalterBright]

"Just the facts, Ma'am"

https://www.youtube.com/watch?v=v4LPkmGO5Cc

[blackearl]

Usually sending just "help" and no other data is preferred. Don't send screenshots, don't make use of the ingame reporting tools (pressing F11), don't send steps to replicate.