Comments are the bread and butter of how work gets done in Jira. They're a place where we can come to hash out discussions that can't be expressed in workflow transitions or due dates. They're a place where we can ask for help if we're waffling about what to do next. But if you're not using wiki markup in your comments, then you're not milking comments for all they're worth. Don't be a silly sausage, take the time to learn wiki markup!
Although it is possible to set the Comment field in Jira to use the default text renderer, the majority of Jira installations use the wiki markup renderer. Wiki markup allows you to apply a wide range of effects and formats to your comments, allowing them to become more than simply a block of text. The great thing about wiki markup is that you can provide links, tables, and images in the context of the discussion, rather than hoping your audience will find the correct content elsewhere in the issue.
The wiki markup renderer is available for any text field in Jira but is most often used for multi-line text fields including the Comment field. You can tell if a field allows wiki markup when you see the 'preview' and 'wiki markup help' links located under the text box. The 'preview' link allows you to see your field in all of its marked up glory before saving it. The 'wiki markup help' link pops up a thorough help page regarding wiki notation that is much more comprehensive than what I'll be covering in this blog.
There are many useful wiki markup notations available – too many to discuss in a single blog post. Instead of going through them all, I'll just pick out a few of my favorites. Remember that you can use the 'wiki markup help' link to see a thorough listing and examples of wiki markup.
example notation: h2.Header Text
Headers range from h1 (biggest) to h6 (smallest) and allow you to organize your post into neat segments.
example notation: *strong text similar to bold* _emphasis text similar to italic_ +inserted text similar to underlined+
Though there is no graphical interface for wiki markup text fields, you still have access to all of the standard text effects if you know the notation.
example notation:
|| Table Header Cell 1 || Table Header Cell 2 ||
| Row 1 Cell 1 | Row 1 Cell 2 |
| Row 2 Cell 1 | Row 2 Cell 2 |
Tables in wiki markup are a fantastic way to organize data without having to worry about attaching a spreadsheet.
example notation: !picturefile.jpg|thumbnail! [^textfile.txt]
To use either of these notations, you must first have the referenced file attached to the issue. For attached images, you can display a full sized image or just a thumbnail of the image in your comment so you can be explicitly clear which file you're referencing. You can use the same notation (using exclamations) to reference certain video and audio formats as well. We use a slightly different notation to reference other files that are attached to the issue when we're not concerned with displaying them, but simply linking to them (see the textfile example above).
example notation: [~username]
Mentioning a user will send them an email notification! Hooray! As long as you have permission to view usernames in Jira, you will be offered auto-complete options once you start typing a username. You may also initiate the auto-complete options by using @username instead, but you must select an auto-complete option for this to work (as it will then convert your selection to the correct syntax).
example notation: [http://www.servicerocket.com] [ServiceRocket|http://www.servicerocket.com] http://www.servicerocket.com ISSUEKEY-245
The first two examples above are specifically notated as links in wiki markup. The second example allows you to place alternate text in place of the actual URL, and will read as ServiceRocket. The third example above, however, will work just fine, and you don't need to use explicit notation if you're happy with the full URL displaying. The fourth example is something that every Jira user should know about; If you type a correctly formatted issue key into any text field in Jira, whether it uses wiki markup or not, it will present as a link to that issue.
example notation:
* bullet 1
** sub-bullet 1
* bullet 2
* bullet 3
Everyone loves a good list, and they're very easy to put together with wiki markup. Just make sure to leave a space between the * and your text. You can also use # in place of the * to put together a numbered list!
I've put together an example that makes extensive use of wiki markup to entice you to learn more about it. Study it closely and you could be the prettiest commenter in your instance!
The latest test results are in for the new Breakfast-bot prototypes.
h2.Results
|| Designation || Coffee Test || Bacon Test || Waffle Test || Hash Brown Test || Notes ||
| BB-7 | (x) | (/) | (/) | (x) | [^BB7 test notes.txt] |
| BB-8 | (x) | (x) | (/) | (x) | [^BB8 test notes.txt] |
| BB-9 | (x) | (/) | (x) | (x) | [^BB9 test notes.txt] |
h2.Proposed Modifications
We'll need to make the following modifications to the Three Laws or we'll never get Breakfast-bot out of beta.
# A robot may not injure a human being or, through inaction, allow a human being to come to harm.
#* Breakfast-bot must allow coffee temperatures above 130°F. A coffee maker that makes normal coffee should not be recognized as a threat.
!test8.jpg|thumbnail!
#* Breakfast-bot must not recognize potatoes as humans or we'll never get proper hash browns.
# A robot must obey the orders given it by human beings, except where such orders would conflict with the First Law.
#* Breakfast-bot must understand what +rye+ toast is. In our first rye toast test, Breakfast-bot made +wry+ toast with the words "I'm burnt out" burnt into the toast.
# A robot must protect its own existence as long as such protection does not conflict with the First or Second Law.
#* Breakfast-bot *must not* underestimate how hot the waffle iron can get.
bq. If you can't stand the heat, get out of the kitchen.
----
h2.Further Considerations
* [~bill.cushard], should we be monitoring the _NH_~4~^+^ levels in the cleaning solution?
* We need to get the class into [TrainingRocket|http://www.learndot.com]
* (!) Still no explanation for BB-6's implosion. See IMPL01-251.
