You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucy.apache.org by Marvin Humphrey <ma...@rectangular.com> on 2010/03/04 18:28:19 UTC
Composing posts for both JIRA and email (was a JIRA post)
(CC to lucy-dev and general, reply-to set to general)
On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
> (Warning, this post is long, and is easier to read in JIRA)
I consume email from many of the Lucene lists, and I hate it when people force
me to read stuff via JIRA. It slows me down to have to jump to all those
forum web pages. I only go the web page if there are 5 or more posts in a row
on the same issue that I need to read.
For what it's worth, I've worked out a few routines that make it possible to
compose messages which read well in both mediums.
* Never edit your posts unless absolutely necessary. If JIRA used diffs,
things would be different, but instead it sends the whole frikkin' post
twice (before and after), which makes it very difficult to see what was
edited. If you must edit, append an "edited:" block at the end to
describe what you changed instead of just making changes inline.
* Use FireFox and the "It's All Text" plugin, which makes it possible to edit
JIRA posts using an external editor such as Vim instead of typing into a
textarea. <http://trac.gerf.org/itsalltext>
* After editing, use the preview button (it's a little monitor icon to the
upper right of the textarea) to make sure the post looks good in JIRA.
* Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
mechanisms look so crappy in email. This is easy from Vim, because
rewrapping a long line (by typing "gq" from visual mode to rewrap the
current selection) that starts with "> " causes "> " to be prepended to
the wrapped lines.
* Use asterisk bullet lists liberally, because they look good everywhere.
* Use asterisks for *emphasis*, because that looks good everywhere.
* If you wrap lines, use a reasonably short line length. (I use 78; Mike
McCandless, who also wraps lines for his Jira posts, uses a smaller
number). Otherwise you'll get nasty wrapping in narrow windows, both in
email clients and web browsers.
There are still a couple compromises that don't work out well. For email,
ideally you want to set off code blocks with indenting:
int foo = 1;
int bar = 2;
To make code look decent in JIRA, you have to wrap that with {code} tags,
which unfortunately look heinous in email. Left-justifying the tags but
indenting the code seems like it would be a rotten-but-salvageable compromise,
as it at least sets off the tags visually rather than making them appear as
though they are part of the code fragment.
{code}
int foo = 1;
int bar = 2;
{code}
Unfortunately, that's going to look like this in JIRA, because of a bug that
strips all leading whitespace from the first line.
|-------------------------|
| int foo; |
| int bar; |
|-------------------------|
It seems that this has been fixed by Atlassian in the Confluence wiki
(<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
JIRA installation at issues.apache.org. So for now, I manually strip
indentation until the whole block is flush left.
{code}
int foo = 1;
int bar = 2;
{code}
(Gag. I vastly prefer wikis that automatically apply fixed-width styling to
any indented text.)
One last tip for Lucy developers (and other non-Java devs). JIRA has limited
syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
only -- and defaults to assuming your code is Java. In general, you want to
override that and tell JIRA to use "none".
{code:none}
int foo = 1;
int bar = 2;
{code}
Marvin Humphrey
Re: Composing posts for both JIRA and email (was a JIRA post)
Posted by Simon Willnauer <si...@googlemail.com>.
Marvin,
thank you for taking the time to write up this great guidelines. Would
you mind adding this to the wiki? I think
this is very valuable for new devs and contributors.
simon
On Thu, Mar 4, 2010 at 6:28 PM, Marvin Humphrey <ma...@rectangular.com> wrote:
> (CC to lucy-dev and general, reply-to set to general)
>
> On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
>
>> (Warning, this post is long, and is easier to read in JIRA)
>
> I consume email from many of the Lucene lists, and I hate it when people force
> me to read stuff via JIRA. It slows me down to have to jump to all those
> forum web pages. I only go the web page if there are 5 or more posts in a row
> on the same issue that I need to read.
>
> For what it's worth, I've worked out a few routines that make it possible to
> compose messages which read well in both mediums.
>
> * Never edit your posts unless absolutely necessary. If JIRA used diffs,
> things would be different, but instead it sends the whole frikkin' post
> twice (before and after), which makes it very difficult to see what was
> edited. If you must edit, append an "edited:" block at the end to
> describe what you changed instead of just making changes inline.
> * Use FireFox and the "It's All Text" plugin, which makes it possible to edit
> JIRA posts using an external editor such as Vim instead of typing into a
> textarea. <http://trac.gerf.org/itsalltext>
> * After editing, use the preview button (it's a little monitor icon to the
> upper right of the textarea) to make sure the post looks good in JIRA.
> * Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
> mechanisms look so crappy in email. This is easy from Vim, because
> rewrapping a long line (by typing "gq" from visual mode to rewrap the
> current selection) that starts with "> " causes "> " to be prepended to
> the wrapped lines.
> * Use asterisk bullet lists liberally, because they look good everywhere.
> * Use asterisks for *emphasis*, because that looks good everywhere.
> * If you wrap lines, use a reasonably short line length. (I use 78; Mike
> McCandless, who also wraps lines for his Jira posts, uses a smaller
> number). Otherwise you'll get nasty wrapping in narrow windows, both in
> email clients and web browsers.
>
> There are still a couple compromises that don't work out well. For email,
> ideally you want to set off code blocks with indenting:
>
> int foo = 1;
> int bar = 2;
>
> To make code look decent in JIRA, you have to wrap that with {code} tags,
> which unfortunately look heinous in email. Left-justifying the tags but
> indenting the code seems like it would be a rotten-but-salvageable compromise,
> as it at least sets off the tags visually rather than making them appear as
> though they are part of the code fragment.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> Unfortunately, that's going to look like this in JIRA, because of a bug that
> strips all leading whitespace from the first line.
>
> |-------------------------|
> | int foo; |
> | int bar; |
> |-------------------------|
>
> It seems that this has been fixed by Atlassian in the Confluence wiki
> (<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
> JIRA installation at issues.apache.org. So for now, I manually strip
> indentation until the whole block is flush left.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> (Gag. I vastly prefer wikis that automatically apply fixed-width styling to
> any indented text.)
>
> One last tip for Lucy developers (and other non-Java devs). JIRA has limited
> syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
> only -- and defaults to assuming your code is Java. In general, you want to
> override that and tell JIRA to use "none".
>
> {code:none}
> int foo = 1;
> int bar = 2;
> {code}
>
> Marvin Humphrey
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Composing posts for both JIRA and email (was a JIRA post)
Posted by Simon Willnauer <si...@googlemail.com>.
Marvin,
thank you for taking the time to write up this great guidelines. Would
you mind adding this to the wiki? I think
this is very valuable for new devs and contributors.
simon
On Thu, Mar 4, 2010 at 6:28 PM, Marvin Humphrey <ma...@rectangular.com> wrote:
> (CC to lucy-dev and general, reply-to set to general)
>
> On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
>
>> (Warning, this post is long, and is easier to read in JIRA)
>
> I consume email from many of the Lucene lists, and I hate it when people force
> me to read stuff via JIRA. It slows me down to have to jump to all those
> forum web pages. I only go the web page if there are 5 or more posts in a row
> on the same issue that I need to read.
>
> For what it's worth, I've worked out a few routines that make it possible to
> compose messages which read well in both mediums.
>
> * Never edit your posts unless absolutely necessary. If JIRA used diffs,
> things would be different, but instead it sends the whole frikkin' post
> twice (before and after), which makes it very difficult to see what was
> edited. If you must edit, append an "edited:" block at the end to
> describe what you changed instead of just making changes inline.
> * Use FireFox and the "It's All Text" plugin, which makes it possible to edit
> JIRA posts using an external editor such as Vim instead of typing into a
> textarea. <http://trac.gerf.org/itsalltext>
> * After editing, use the preview button (it's a little monitor icon to the
> upper right of the textarea) to make sure the post looks good in JIRA.
> * Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
> mechanisms look so crappy in email. This is easy from Vim, because
> rewrapping a long line (by typing "gq" from visual mode to rewrap the
> current selection) that starts with "> " causes "> " to be prepended to
> the wrapped lines.
> * Use asterisk bullet lists liberally, because they look good everywhere.
> * Use asterisks for *emphasis*, because that looks good everywhere.
> * If you wrap lines, use a reasonably short line length. (I use 78; Mike
> McCandless, who also wraps lines for his Jira posts, uses a smaller
> number). Otherwise you'll get nasty wrapping in narrow windows, both in
> email clients and web browsers.
>
> There are still a couple compromises that don't work out well. For email,
> ideally you want to set off code blocks with indenting:
>
> int foo = 1;
> int bar = 2;
>
> To make code look decent in JIRA, you have to wrap that with {code} tags,
> which unfortunately look heinous in email. Left-justifying the tags but
> indenting the code seems like it would be a rotten-but-salvageable compromise,
> as it at least sets off the tags visually rather than making them appear as
> though they are part of the code fragment.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> Unfortunately, that's going to look like this in JIRA, because of a bug that
> strips all leading whitespace from the first line.
>
> |-------------------------|
> | int foo; |
> | int bar; |
> |-------------------------|
>
> It seems that this has been fixed by Atlassian in the Confluence wiki
> (<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
> JIRA installation at issues.apache.org. So for now, I manually strip
> indentation until the whole block is flush left.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> (Gag. I vastly prefer wikis that automatically apply fixed-width styling to
> any indented text.)
>
> One last tip for Lucy developers (and other non-Java devs). JIRA has limited
> syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
> only -- and defaults to assuming your code is Java. In general, you want to
> override that and tell JIRA to use "none".
>
> {code:none}
> int foo = 1;
> int bar = 2;
> {code}
>
> Marvin Humphrey
>
>
Re: Composing posts for both JIRA and email (was a JIRA post)
Posted by Michael McCandless <lu...@mikemccandless.com>.
On Fri, Mar 5, 2010 at 2:09 PM, Marvin Humphrey <ma...@rectangular.com> wrote:
> On Fri, Mar 05, 2010 at 05:36:41AM -0500, Michael McCandless wrote:
>> I don't get why Jira can't support email markup (>, >> means nested
>> levels of quoting) in addition to its own...
>
> With text color corresponding to indent level? That would be ideal. However,
> email quoting used within JIRA is still coherent, while JIRA quoting within
> email is crap.
Right, like it already does when rendering its own markup, or, like
how most email clients render it.
> People probably think I'm quaint for not using the latest hotness in JIRA
> markup, but so long as my communiques are easily consumed, I don't care.
I don't think it's quaint. At the end of the day, here, the goal is
communication (NOT an easy task, often failing since it takes two to
tango). When latest bells and whistles are counter that goal then
it's clear which wins.
I think our difference is whether "most" communication takes place
first read via Jira email (you favor making that readable) or via
click-through to the issue (I slightly favor making this readable --
yes I like the coloring for better communication).
>> It's All Text plugin sounds neat -- what does it gain over simple copy/paste
>> out of your editor?
>
> It's easier to launch the editor -- you click a floating button to the lower
> right of the textarea. Then, when you save the document (which is a temp
> file) and subsequently refocus on the browser application, the textarea
> flashes yellow and the text from the latest save is automatically inserted.
>
> I guess that doesn't sound like too much, but avoiding a few tedious actions
> on something I do a lot makes a difference for me.
Ahh OK, this sounds quite nice. Though my emacs is never more than an
alt-tab away..
> What would be really great is if you could edit iteravely using the text
> editor while using the JIRA preview. Unfortunately, there's a problem with
> the interaction of those two features -- once you click the JIRA preview, the
> It'sAllText editor can no longer update the textarea, even after you disable
> the preview.
Sigh. There's always something...
>> I can't stand that gmail doesn't do the right thing w/ line wrapping
>> outgoing email, though -- when I quote a message (like below), the
>> addition of the >'s causes already wrapped text to be further wrapped,
>> thus looking hideous (you should see examples below).
>
> I don't see any such examples. :) Perhaps that's because I limit my lines to
> 78 characters and gmail wraps at 80?
Hmmmm, interesting. Let me try *not* re-formatting the quoted parts of
this message and see what happens. Maybe it's been fixed (by Google)?
> I rewrap people's quotes, too, to keep them at 78 characters or less. But I'm
> a former graphic designer, so making decisions about type presentation and
> adapting my workflow as needed is second nature and quick.
Sometimes I do that... sometimes I don't... this time I didn't.
Being a former graphic designer is a good way to learn take
communication seriously.
Mike
Re: Composing posts for both JIRA and email (was a JIRA post)
Posted by Marvin Humphrey <ma...@rectangular.com>.
On Fri, Mar 05, 2010 at 05:36:41AM -0500, Michael McCandless wrote:
> I don't get why Jira can't support email markup (>, >> means nested
> levels of quoting) in addition to its own...
With text color corresponding to indent level? That would be ideal. However,
email quoting used within JIRA is still coherent, while JIRA quoting within
email is crap.
People probably think I'm quaint for not using the latest hotness in JIRA
markup, but so long as my communiques are easily consumed, I don't care.
> It's All Text plugin sounds neat -- what does it gain over simple copy/paste
> out of your editor?
It's easier to launch the editor -- you click a floating button to the lower
right of the textarea. Then, when you save the document (which is a temp
file) and subsequently refocus on the browser application, the textarea
flashes yellow and the text from the latest save is automatically inserted.
I guess that doesn't sound like too much, but avoiding a few tedious actions
on something I do a lot makes a difference for me.
What would be really great is if you could edit iteravely using the text
editor while using the JIRA preview. Unfortunately, there's a problem with
the interaction of those two features -- once you click the JIRA preview, the
It'sAllText editor can no longer update the textarea, even after you disable
the preview.
> I can't stand that gmail doesn't do the right thing w/ line wrapping
> outgoing email, though -- when I quote a message (like below), the
> addition of the >'s causes already wrapped text to be further wrapped,
> thus looking hideous (you should see examples below).
I don't see any such examples. :) Perhaps that's because I limit my lines to
78 characters and gmail wraps at 80?
I rewrap people's quotes, too, to keep them at 78 characters or less. But I'm
a former graphic designer, so making decisions about type presentation and
adapting my workflow as needed is second nature and quick.
Marvin Humphrey
> On Thu, Mar 4, 2010 at 12:28 PM, Marvin Humphrey <ma...@rectangular.com> wrote:
> > (CC to lucy-dev and general, reply-to set to general)
> >
> > On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
> >
> >> (Warning, this post is long, and is easier to read in JIRA)
> >
> > I consume email from many of the Lucene lists, and I hate it when people force
> > me to read stuff via JIRA. It slows me down to have to jump to all those
> > forum web pages. I only go the web page if there are 5 or more posts in a row
> > on the same issue that I need to read.
> >
> > For what it's worth, I've worked out a few routines that make it possible to
> > compose messages which read well in both mediums.
> >
> > * Never edit your posts unless absolutely necessary. If JIRA used diffs,
> > things would be different, but instead it sends the whole frikkin' post
> > twice (before and after), which makes it very difficult to see what was
> > edited. If you must edit, append an "edited:" block at the end to
> > describe what you changed instead of just making changes inline.
> > * Use FireFox and the "It's All Text" plugin, which makes it possible to edit
> > JIRA posts using an external editor such as Vim instead of typing into a
> > textarea. <http://trac.gerf.org/itsalltext>
> > * After editing, use the preview button (it's a little monitor icon to the
> > upper right of the textarea) to make sure the post looks good in JIRA.
> > * Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
> > mechanisms look so crappy in email. This is easy from Vim, because
> > rewrapping a long line (by typing "gq" from visual mode to rewrap the
> > current selection) that starts with "> " causes "> " to be prepended to
> > the wrapped lines.
> > * Use asterisk bullet lists liberally, because they look good everywhere.
> > * Use asterisks for *emphasis*, because that looks good everywhere.
> > * If you wrap lines, use a reasonably short line length. (I use 78; Mike
> > McCandless, who also wraps lines for his Jira posts, uses a smaller
> > number). Otherwise you'll get nasty wrapping in narrow windows, both in
> > email clients and web browsers.
> >
> > There are still a couple compromises that don't work out well. For email,
> > ideally you want to set off code blocks with indenting:
> >
> > int foo = 1;
> > int bar = 2;
> >
> > To make code look decent in JIRA, you have to wrap that with {code} tags,
> > which unfortunately look heinous in email. Left-justifying the tags but
> > indenting the code seems like it would be a rotten-but-salvageable compromise,
> > as it at least sets off the tags visually rather than making them appear as
> > though they are part of the code fragment.
> >
> > {code}
> > int foo = 1;
> > int bar = 2;
> > {code}
> >
> > Unfortunately, that's going to look like this in JIRA, because of a bug that
> > strips all leading whitespace from the first line.
> >
> > |-------------------------|
> > | int foo; |
> > | int bar; |
> > |-------------------------|
> >
> > It seems that this has been fixed by Atlassian in the Confluence wiki
> > (<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
> > JIRA installation at issues.apache.org. So for now, I manually strip
> > indentation until the whole block is flush left.
> >
> > {code}
> > int foo = 1;
> > int bar = 2;
> > {code}
> >
> > (Gag. I vastly prefer wikis that automatically apply fixed-width styling to
> > any indented text.)
> >
> > One last tip for Lucy developers (and other non-Java devs). JIRA has limited
> > syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
> > only -- and defaults to assuming your code is Java. In general, you want to
> > override that and tell JIRA to use "none".
> >
> > {code:none}
> > int foo = 1;
> > int bar = 2;
> > {code}
> >
> > Marvin Humphrey
> >
> >
Re: Composing posts for both JIRA and email (was a JIRA post)
Posted by Michael McCandless <lu...@mikemccandless.com>.
Great guidelines Marvin!
I agree w/ most of this, except, I do use Jira's markup (bq., {quote})
when adding comments. I'm torn between how important the "first read"
(via the email Jira sends) is vs the "I click through to the issue &
read it). Typically I just click through to the issue unless it's a
smallish comment.
I don't get why Jira can't support email markup (>, >> means nested
levels of quoting) in addition to its own... maybe they are gunning
for some kind of lock-in of their users. EG I've seen people respond
to normal email threads, but quoting using bq.!
Sometimes I compose with an external editor (in emacs, which wraps)
sometimes directly in the browser. It's All Text plugin sounds neat
-- what does it gain over simple copy/paste out of your editor?
I can't stand that gmail doesn't do the right thing w/ line wrapping
outgoing email, though -- when I quote a message (like below), the
addition of the >'s causes already wrapped text to be further wrapped,
thus looking hideous (you should see examples below).
And yes I hate that the first line under {code} has no indentation.
Silly. Sounds like we just need a Jira upgrade @ Apache to fix that
one...
Mike
On Thu, Mar 4, 2010 at 12:28 PM, Marvin Humphrey <ma...@rectangular.com> wrote:
> (CC to lucy-dev and general, reply-to set to general)
>
> On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
>
>> (Warning, this post is long, and is easier to read in JIRA)
>
> I consume email from many of the Lucene lists, and I hate it when people force
> me to read stuff via JIRA. It slows me down to have to jump to all those
> forum web pages. I only go the web page if there are 5 or more posts in a row
> on the same issue that I need to read.
>
> For what it's worth, I've worked out a few routines that make it possible to
> compose messages which read well in both mediums.
>
> * Never edit your posts unless absolutely necessary. If JIRA used diffs,
> things would be different, but instead it sends the whole frikkin' post
> twice (before and after), which makes it very difficult to see what was
> edited. If you must edit, append an "edited:" block at the end to
> describe what you changed instead of just making changes inline.
> * Use FireFox and the "It's All Text" plugin, which makes it possible to edit
> JIRA posts using an external editor such as Vim instead of typing into a
> textarea. <http://trac.gerf.org/itsalltext>
> * After editing, use the preview button (it's a little monitor icon to the
> upper right of the textarea) to make sure the post looks good in JIRA.
> * Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
> mechanisms look so crappy in email. This is easy from Vim, because
> rewrapping a long line (by typing "gq" from visual mode to rewrap the
> current selection) that starts with "> " causes "> " to be prepended to
> the wrapped lines.
> * Use asterisk bullet lists liberally, because they look good everywhere.
> * Use asterisks for *emphasis*, because that looks good everywhere.
> * If you wrap lines, use a reasonably short line length. (I use 78; Mike
> McCandless, who also wraps lines for his Jira posts, uses a smaller
> number). Otherwise you'll get nasty wrapping in narrow windows, both in
> email clients and web browsers.
>
> There are still a couple compromises that don't work out well. For email,
> ideally you want to set off code blocks with indenting:
>
> int foo = 1;
> int bar = 2;
>
> To make code look decent in JIRA, you have to wrap that with {code} tags,
> which unfortunately look heinous in email. Left-justifying the tags but
> indenting the code seems like it would be a rotten-but-salvageable compromise,
> as it at least sets off the tags visually rather than making them appear as
> though they are part of the code fragment.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> Unfortunately, that's going to look like this in JIRA, because of a bug that
> strips all leading whitespace from the first line.
>
> |-------------------------|
> | int foo; |
> | int bar; |
> |-------------------------|
>
> It seems that this has been fixed by Atlassian in the Confluence wiki
> (<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
> JIRA installation at issues.apache.org. So for now, I manually strip
> indentation until the whole block is flush left.
>
> {code}
> int foo = 1;
> int bar = 2;
> {code}
>
> (Gag. I vastly prefer wikis that automatically apply fixed-width styling to
> any indented text.)
>
> One last tip for Lucy developers (and other non-Java devs). JIRA has limited
> syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
> only -- and defaults to assuming your code is Java. In general, you want to
> override that and tell JIRA to use "none".
>
> {code:none}
> int foo = 1;
> int bar = 2;
> {code}
>
> Marvin Humphrey
>
>