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 <[email protected]> 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
>
>
