Last Comment Bug 604237 - Clean up the format of HTML Emails
: Clean up the format of HTML Emails
Status: RESOLVED FIXED
:
Product: Bugzilla
Classification: Server Software
Component: Email Notifications (show other bugs)
: 4.1
: All All
: -- enhancement (vote)
: Bugzilla 4.2
Assigned To: Guy Pyrzak
: default-qa
Mentors:
Depends on:
Blocks: 691697 735821
  Show dependency treegraph
 
Reported: 2010-10-13 16:47 PDT by Max Kanat-Alexander
Modified: 2012-03-21 08:24 PDT (History)
10 users (show)
mkanat: approval+
mkanat: approval4.2+
mkanat: blocking4.2+
See Also:
QA Whiteboard:
Iteration: ---
Points: ---


Attachments
v1 (2.18 KB, patch)
2011-04-24 15:53 PDT, Guy Pyrzak
mkanat: review-
Details | Diff | Review
v2 (2.24 KB, patch)
2011-09-02 08:48 PDT, Guy Pyrzak
mkanat: review+
Details | Diff | Review

Description Max Kanat-Alexander 2010-10-13 16:47:26 PDT
The format of HTML emails could be spiffed up a bit. Here are some of my suggestions:

* The diffs section could say "Max K-A changed bug 2323" instead of having "Bug 2323" above the table. (The spacing between "Bug 2323" and the table looks a bit odd.)
* The "footer" should probably be separated from the content by an <hr>.
* I think the table cells for the diffs table probably need some padding.

Also, we should probably add some CSS for the clients that support it.

Anyhow, these are all suggestions, but the general cleanup of HTML email should be done in this bug.
Comment 1 Guy Pyrzak 2010-10-18 12:22:22 PDT
I'll get on this ASAP. just got back from vacation.

Adding faaborg and legneato since they both have shown some interest in bugzilla stuff, but hopefully he can add more people and we can get more "things to fix" added to this list.
Comment 2 Alex Faaborg [:faaborg] (Firefox UX) 2010-10-19 17:05:09 PDT
>* The diffs section could say "Max K-A changed bug 2323" instead of having
>"Bug 2323" above the table.

I would go farther and get rid of the table entirely. So:

Guy Pyrzak <guy.pyrzak@gmail.com> changed:

          What    |Removed                     |Added
----------------------------------------------------------------------------
                CC|                            |clegnitto@mozilla.com,
                  |                            |faaborg@mozilla.com,
                  |                            |LpSolit@gmail.com


Becomes the sentence:

"Guy Pyrzak cc'd Alex Faaborg, Christian Legneato and Frédéric Buclin"

(where the name are mailto: links)

few other examples:

"Alex Faaborg set this bug as a duplicate of [Summary of duplicated bug as a hyperlink]"

"Christian Legneato set the flag blocking-3.7+"

"Alex Limi added the keyword ux-jargon"

The challenge with reading the current emails isn't that they are plain text versus HTML, it's that they contain a table that separates subject verb and object(s) so that it takes a moment to visually scan and mentally construct exactly what exactly happened.

There are some localization issues with building sentences out of the data in the table, but even if we just deployed sentences for en-us/gb, I think it would make the experience of reading bugmail considerably faster for users in that local.
Comment 3 Max Kanat-Alexander 2010-10-19 17:23:52 PDT
  Hey Alex. Thanks for the feedback. Have you seen the new HTML emails yet? I think perhaps they may handle some of the visual objections that you have.

  I have used other bug trackers that attempt to form sentences about bugmail changes, and I find it obnoxious, because I (like most developers) get a TON of bugmail, and all I want to do with most of it is scan it, not read every one in detail. The table format makes it much easier to instantly scan the bugmail and understand whether or not it's relevant to me. If it's in sentences, I cannot scan it, I must read it.
Comment 4 Alex Faaborg [:faaborg] (Firefox UX) 2010-10-19 18:16:53 PDT
>The table format makes it much easier to instantly scan the bugmail and
>understand whether or not it's relevant to me. If it's in sentences, I cannot
>scan it, I must read it.

Interesting, so the time to read goes down because one can infer information from the general structure of the table?  I of course get no shortage of bugmail myself, but haven't had a chance to try reading large quantities in sentence form.

There are of course some easy ways to make the sentence scan able without reading, like using colored words for the actions (assuming that the action is the piece of information that people are going to filter on for relevance).

>Have you seen the new HTML emails yet?

Not yet, where can I view them?
Comment 5 Frédéric Buclin 2010-10-19 18:20:08 PDT
I also find it easier and faster to scan tables than to read sentences to quickly get information. I remember we had this discussion several months (years?) ago about how to display data in show_bug.cgi.
Comment 6 Alex Faaborg [:faaborg] (Firefox UX) 2010-10-19 18:23:09 PDT
I don't think the question of which of the two is better, as opposed to can we design something that is even more scan-able, and even easier to linearly read?
Comment 7 Guy Pyrzak 2010-10-19 18:42:29 PDT
(In reply to comment #4)
> >Have you seen the new HTML emails yet?
> 
> Not yet, where can I view them?

You can go to landfill, set the prefs to email you no matter what (even if you filed/edited the bug) and then file a bug. It should work then.

The table vs sentence thing is a concept that I've been toying with in my head but I also know that many developers are very attached to their tables, both in the edit bug form and in the bugmail. I know Aza developed a UI for Bugzilla that displayed the bug info as a sentence and I personally loved it.

I do want to experiment with this idea, in bugmail, the diffs in general and in the bugform, but I'm not sure if that's the flavor of changes we're looking for in this bug since that's not an improvement to HTML bugmail but to how we display data as a whole.

thoughts?

BTW bug 11368 talks about moving the bug history into the comments and this would be another great place for sentences to show up instead of tables IMO.
Comment 8 christian 2010-10-19 19:26:13 PDT
I was thinking history items such as those in bug 11368 and the bugzilla tweaks extension might be a good format to follow for this too.

So this:

Guy Pyrzak <guy.pyrzak@gmail.com> changed:

          What    |Removed                     |Added
----------------------------------------------------------------------------
                CC|                            |clegnitto@mozilla.com,
                  |                            |faaborg@mozilla.com,
                  |                            |LpSolit@gmail.com


becomes...

Guy Pyrzak <guy.pyrzak@gmail.com> made the following changes:

* CC: clegnitto@mozilla.com, faaborg@mozilla.com, LpSolit@gmail.com

and 

Guy Pyrzak <guy.pyrzak@gmail.com> changed:

          What    |Removed                     |Added
----------------------------------------------------------------------------
     blocking1.9.2| blocking1.9.2?             |blocking1.9.2.12+


becomes...

Guy Pyrzak <guy.pyrzak@gmail.com> made the following changes:

* blocking1.9.2: <del>blocking1.9.2?</del> &rarr; blocking1.9.2.12+

Not sure if it is better, but seems to be a middle road between the table and the sentences. We could also make the sentences a user or admin option and default to something a little more technical.
Comment 9 christian 2010-10-19 19:28:51 PDT
err, for a screenshot with markup see https://bug11368.bugzilla.mozilla.org/attachment.cgi?id=482259 of course
Comment 10 u88484 2010-10-21 13:47:54 PDT
I hate the tables.  I read most of my emails on my phone and can barely ever tell what exactly was added/removed because the tables are almost always screwed up, especially when more than one thing was changed.  At least with the email being in HTML format I could scroll the email to see everything instead of the text based version just breaking up the tables how ever it pleases.
Comment 11 Guy Pyrzak 2010-10-21 13:53:45 PDT
the HTML email uses HTML tables which should render fine on  your phone and since it uses HTML tables it will be somewhat elastic. 

But I am hearing loud and clear "we'd prefer something other than tables! I think we should file another bug and we could fix this in multiple pages, or at least discuss that.

Any fixes to the actual HTML bugmail, which can be seen on landfill currently. see comment 7 for more details.
Comment 12 Max Kanat-Alexander 2010-10-21 13:56:19 PDT
(In reply to comment #11)
> But I am hearing loud and clear "we'd prefer something other than tables! I
> think we should file another bug and we could fix this in multiple pages, or at
> least discuss that.

  Okay, that sounds reasonable. For this bug, let's not worry about changing away from tables--particularly since most of the complaints are about the text tables, which I also frequently find difficult (although mostly for long values like the Whiteboard). Sounds like we should file another bug for the possibility of switching bugmail to some other system. Of course, we may want to wait for experienced user input on the HTML emails with the HTML tables--that is, let people use those for a while before making a decision based on the old experience of text tables.
Comment 13 Alex Faaborg [:faaborg] (Firefox UX) 2010-10-27 22:28:28 PDT
>I think we should file another bug

I posted some ideas over to bug 607829
Comment 14 Max Kanat-Alexander 2011-03-28 23:10:50 PDT
BTW, whenever we get a "blocking 4.2" flag, I will consider this to be a blocker. It's definitely something we should handle before release.
Comment 15 Guy Pyrzak 2011-04-24 15:53:28 PDT
Created attachment 528029 [details] [diff] [review]
v1
Comment 16 Max Kanat-Alexander 2011-04-24 15:57:54 PDT
Comment on attachment 528029 [details] [diff] [review]
v1

Review of attachment 528029 [details] [diff] [review]:

I haven't looked at this actually rendered yet (do you have a screenshot?) but just one code comment:

::: template/en/default/email/bugmail.html.tmpl
@@ +71,5 @@
       [% IF !isnew && change.who.login != last_changer %]
         [% last_changer = change.who.login %]
+        [% IF in_table == true %]
+          </table>
+          [% SET in_table = false %]

Why not just have a table_start and table_end block? (That is, make table_maker into table_start and then this </table> thing can be table_end.)
Comment 17 Max Kanat-Alexander 2011-06-13 16:28:01 PDT
Comment on attachment 528029 [details] [diff] [review]
v1

Bugmail for new bugs now looks really weird--there's a new table for every field.

Also, for some reason, when I update a bug, Bugzilla now throws a CodeError with no traceback:

file error - table_maker: not found
Comment 18 Michael[tm] Smith 2011-06-20 01:44:38 PDT
(In reply to comment #11)
> But I am hearing loud and clear "we'd prefer something other than tables! I
> think we should file another bug and we could fix this in multiple pages, or
> at least discuss that.

In place of the table formatting, or at least as an option for an alternative to it, I would suggest using a <dl>, <dt>, and <dd>

For example. something like the following:

<dl>
<dt>Priority</dt>
<dd>Removed: Normal</dd>
<dd>Added: High</dd>
</dl>
Comment 19 Max Kanat-Alexander 2011-06-20 15:32:35 PDT
(In reply to comment #18)
> In place of the table formatting, or at least as an option for an
> alternative to it, I would suggest using a <dl>, <dt>, and <dd>

  Thanks for the suggestion. What you may really want to see is something more like bug 607829, which is the long-term future of bugmail. For now I think we're going to stick with the table since it's vertically compact, and there's a lot of value to that in a lot of email-reading contexts.
Comment 20 Michael[tm] Smith 2011-06-20 20:06:15 PDT
(In reply to comment #19)
> (In reply to comment #18)
> > In place of the table formatting, or at least as an option for an
> > alternative to it, I would suggest using a <dl>, <dt>, and <dd>
> 
>   Thanks for the suggestion. What you may really want to see is something
> more like bug 607829, which is the long-term future of bugmail.

OK, thanks -- I'll take a look.

> For now I think we're going to stick with the table since it's vertically compact, and
> there's a lot of value to that in a lot of email-reading contexts.

I hear what you're saying, but please recognize that by doing so you are making a choice to favor vertical compactness over screenreader-friendliness (and mobile-phone-friendliness as well).  I'm not saying that is absolutely the wrong choice, just that it is a choice. You can't really have things both ways (unless you end up, say, providing a user option for non-table-formatted HTML output).

I think you also have to ask yourselves how much your actual users care about vertical compactness of their bugmail. I don't know, maybe you've already gotten a lot of feedback from users that they strongly prefer to have vertical compactness over a list-formatted approach, and that's what's driving your design decisions here.

But FWIW, as one of your users, I want to let you know that I don't really favor vertical compactness much at all. I don't really care how visually attractive my bugmail is, as long as it's readable. Yeah, I realize a list-formatted approach means I'm going to have to scroll down more in my mail client to read the whole message. But frankly, big whoop. It's not going to cause an unreasonable amount of extra scrolling, as far as I can see. I read a ton of bugmail from multiple systems daily, and I know from experience that I could quickly get used to reading it in a list format instead, and it would not be any kind of hardship for me to do that.

Anyway, I am of course just one user among many; I just wanted to give you that feedback for you to take into consideration along with what you get from other users about this.
Comment 21 Max Kanat-Alexander 2011-08-16 16:35:41 PDT
pyrzak: Any updates for this bug? This is one of the big 4.2 blockers.
Comment 22 Guy Pyrzak 2011-09-02 08:48:02 PDT
Created attachment 557844 [details] [diff] [review]
v2

apparently true false didn't work so well, neither did that additional process from inside a block
Comment 23 Max Kanat-Alexander 2011-09-02 19:59:53 PDT
Comment on attachment 557844 [details] [diff] [review]
v2

Review of attachment 557844 [details] [diff] [review]:
-----------------------------------------------------------------

This looks great! However, there should be more space between "mkanat changed bug 2323" and the diffs table. Perhaps just add a <br> after that, on checkin?
Comment 24 Guy Pyrzak 2011-09-06 22:30:32 PDT
Committing to: bzr+ssh://guy.pyrzak%40gmail.com@bzr.mozilla.org/bugzilla/trunk/                                                       
modified template/en/default/email/bugmail.html.tmpl
Committed revision 7951.

Committing to: bzr+ssh://guy.pyrzak%40gmail.com@bzr.mozilla.org/bugzilla/4.2/                                                         
modified template/en/default/email/bugmail.html.tmpl
Committed revision 7920.
Comment 25 Frédéric Buclin 2011-09-07 05:26:15 PDT
Commit message from pyrzak, for this bug:

"Bug 684946 - The word "Version is hard coded; not all pages use field_descs.version"

pyrzak, drug is bad! :)


Anyway, the committed patch causes bustage due to unfiltered [% in_table %] directives. But

  [% in_table %]</table>

and

  <table border="1" cellspacing="0" cellpadding="8">[% in_table%]

do not make any sense to me. [% in_table %] should not be there. So I removed them:

Committing to: bzr+ssh://lpsolit%40gmail.com@bzr.mozilla.org/bugzilla/trunk/
modified template/en/default/email/bugmail.html.tmpl
Committed revision 7952.

Committing to: bzr+ssh://lpsolit%40gmail.com@bzr.mozilla.org/bugzilla/4.2/
modified template/en/default/email/bugmail.html.tmpl
Committed revision 7921.

Note You need to log in before you can comment on or make changes to this bug.