1275799 - Add descriptions to crash report fields

Status: RESOLVED FIXED

(Socorro :: Webapp, task)

Description

[Nicholas Nethercote [inactive]]

When viewing a single crash report, the "Details" and "Metadata" tabs have a lot of fields: Signature, UUID, Date Processed, etc. The meaning of some of these is obvious, but for some it is much less obvious ("EMCheckCompatibility", anyone?). As a result, there are documents explaining some of these fields, such as:

https://support.mozilla.org/en-US/kb/contributors-crash-course#w_how-to-read-httpscrash-stats-mozilla-com

https://support.mozilla.org/en-US/kb/helping-crashes#w_other-helpful-parts-of-a-crash-report

Much better would be if crash-stats itself had descriptions. Tooltips are one possible way of doing this. The description would describe what the field contains, and when appropriate, also extra information about how it can be used.

The tooltips in Firefox's about:memory page would serve as a good model here.

I'm happy to write the descriptions, but I don't know the first thing about crash-stats' code so I'll likely need some help getting the descriptions into the code.

Comment 1

[Nicholas Nethercote [inactive]]

(There's also a lot of field shown in both the "Details" and "Metadata" tab for no obvious reason. Can we remove the duplication, or combine the two tabs into one? I can file a new bug if this is a reasonable idea...)

Comment 2

[Nicholas Nethercote [inactive]]

peterbe, does this sound like a reasonable idea to you?

Comment 3

[Peter Bengtsson [:peterbe]]

Two things going on here...

A) about the descriptions for each field. I think that's a great idea! We have an open bug about needing those descriptions for something else. Adrian is taking a lead on that. But if we can make it so that people like you can help it would be awesome. 

B) The second tab, "Metadata" was added much later than the "Details" tab. There was a time when the Details tab didn't change very much but eventually it got too tedious to keep up so we made the Metadata tab which just lists ALL keys. We COULD just merge them and list all. Certain keys need custom presentation. For example, that additional message that appears next to the URL and Email values. We could also have the ordering be custom. Certain few ones get elevated and the rest just follows. What do you think?

Comment 4

[Nicholas Nethercote [inactive]]

I've got my hands on the Socorro source code now. I see how the "Details" tab is a bespoke presentation while "Metadata" is just a dump of everything. Which means:

- Just adding descriptions for "Details" fields in the "Details" tab is easy.
- Adding descriptions for "Metadata" fields is harder.
- Adding custom presentation for "Metadata" fields is harder.
- Combining "Details" and "Metadata" in a nice way is harder.

> There was a time when the Details tab didn't change very much but eventually it got
> too tedious to keep up so we made the Metadata tab which just lists ALL keys

Ok. From a user's point of view, the nicest thing would probably be to have a single tab with all fields, in a nice order, with custom presentation as necessary, and descriptions. Sounds like the main obstacle preventing that is potential maintenance hassle if the fields change a lot. So... how often do they change?

Comment 5

[Peter Bengtsson [:peterbe]]

(In reply to Nicholas Nethercote [:njn] from comment #4)
> I've got my hands on the Socorro source code now. I see how the "Details"
> tab is a bespoke presentation while "Metadata" is just a dump of everything.
> Which means:
> 
> - Just adding descriptions for "Details" fields in the "Details" tab is easy.
> - Adding descriptions for "Metadata" fields is harder.
> - Adding custom presentation for "Metadata" fields is harder.
> - Combining "Details" and "Metadata" in a nice way is harder.
> 
> > There was a time when the Details tab didn't change very much but eventually it got
> > too tedious to keep up so we made the Metadata tab which just lists ALL keys
> 
> Ok. From a user's point of view, the nicest thing would probably be to have
> a single tab with all fields, in a nice order, with custom presentation as
> necessary, and descriptions. Sounds like the main obstacle preventing that
> is potential maintenance hassle if the fields change a lot. So... how often
> do they change?

They change about 1-2 new fields per month.

Comment 6

[Nicholas Nethercote [inactive]]

(In reply to Nicholas Nethercote [:njn] from comment #4)
> I've got my hands on the Socorro source code now. I see how the "Details"
> tab is a bespoke presentation while "Metadata" is just a dump of everything.
> Which means:
> 
> - Just adding descriptions for "Details" fields in the "Details" tab is easy.
> - Adding descriptions for "Metadata" fields is harder.
> - Adding custom presentation for "Metadata" fields is harder.
> - Combining "Details" and "Metadata" in a nice way is harder.

I'll just start with the first of these for now. Others can be potential follow-ups.

I found that a couple of the fields already have descriptions:

> <tr>
>     <th title="Notes added by the application's code during crash" scope="row">App Notes</th>
>     <td>
>         <pre>{{ report.app_notes }}</pre>
>     </td>
> </tr>
> {% endif %}
> {% if report.processor_notes %}
> <tr>
>     <th title="Notes added by Socorro when accepting the crash report" scope="row">Processor Notes</th>
>     <td>
>         <code>{{ report.processor_notes }}</code>
>     </td>
> </tr>

So I can do likewise. My only remaining question: some of these descriptions
might be relatively long, e.g. multiple sentences. Is there a better way to do
it than just putting it all on a single very long line?

(Also, what's the preferred way to receive Socorro patches? Do you use Bugzilla
or GitHub?)

Comment 7

[Nicholas Nethercote [inactive]]

Ok, I've done a first pass at this. I made a PR at https://github.com/mozilla/socorro/pull/3360. How do I make an attachment that links to the PR? (Like the one in bug 803779, for example.)

I'm not entirely sure who is best to review this, so I'm needinfo'ing a few people who might be interested. I apologize in advance for not knowing how to handle Socorro bugs/PRs properly. Thank you.

Comment 8

[Nicholas Nethercote [inactive]]

Attachment: Link to PR

Comment 9

[[DEACTIVATED] Adrian Gaudebert]

Nicholas, this is great! I think we should merge our parallel efforts on this matter (documenting crash data), as I am working on something very similar in bug 1275482. 

I would take a different approach to this bug. I think we should make our Super Search Fields list our source of truth for crash documentation. The advantage of that is that it's all in database (no need to make a full deploy to update a description), and it is available through our public API. It would also make the code easier to maintain, as adding the descriptions would be automated with some templating sugar. 

My proposition is to move all your descriptions into our database, then rework that patch to pull the data from it instead. I can take it from there if you'd like.

Comment 10

[Nicholas Nethercote [inactive]]

(In reply to Adrian Gaudebert [:adrian] from comment #9)
> Nicholas, this is great! I think we should merge our parallel efforts on
> this matter (documenting crash data), as I am working on something very
> similar in bug 1275482. 

I see; apologies for the duplication of effort. I didn't properly comprehend what you were doing in that bug.

> I would take a different approach to this bug. I think we should make our
> Super Search Fields list our source of truth for crash documentation. The
> advantage of that is that it's all in database (no need to make a full
> deploy to update a description), and it is available through our public API.
> It would also make the code easier to maintain, as adding the descriptions
> would be automated with some templating sugar. 
> 
> My proposition is to move all your descriptions into our database, then
> rework that patch to pull the data from it instead. I can take it from there
> if you'd like.

That sounds good. I think this means that we could get tooltips in both the "Details" and "Metadata" tabs, correct?

This bug should remain open, for the addition of the tooltips (sourced from the database), and the various presentation tweaks that I've made. But I can wait until bug 1275482 is finished before doing that.

Comment 11

[Peter Bengtsson [:peterbe]]

Great work Nicholas. But I have to agree with Adrian, "I think we should make our Super Search Fields list our source of truth for crash documentation.". If we have the descriptions written down properly in our database we can insert them into the HTML on-the-fly.

Your PR has great value in terms of the content, but I think I'd rather let Adrian invite you into the participation of typing that into the Super Search Fields database.

Comment 12

[[DEACTIVATED] Adrian Gaudebert]

Attachment: Link to Github pull-request: https://github.com/mozilla/socorro/pull/3368

Comment 13

[[github robot]]

Commit pushed to master at https://github.com/mozilla/socorro

https://github.com/mozilla/socorro/commit/efdc7aa3e0782572e1e2524f791da9539702441c
Fixes bug 1275799 - Added a title with a description of each field in report/index/. (#3368)

* Fixes bug 1275799 - Added a title with a description of each field in report/index/.

* review