Technical writers and public speaking

Technical writers and public speaking – a match made in heaven? We have the knowledge about and passion for our field. We can safely put one word after another without causing mayhem. But can we stand up and speak in front of a crowd? More importantly, what would we do when confronted by a chandelier?

To find out whether you can do it or not, try Scott Berkun‘s book, Confessions of a public speaker. I’ve just finished reading the book, with great enjoyment and plentiful note taking.

Technical communicators who do it already

Anne Gentle, Janet Swisher, Tony Self, Rhonda Bracey, Char James-Tanny, Tom Johnson, Sue Heim, Joe Welinske, Ellis Pratt, and many more. All excellent speakers and presenters. Perhaps most people reading this post have a public-speaking story to tell, either of horror or of triumph.

Until two years ago, you could have blown me down with a feather duster if you’d told told me that I would speak at a conference. Then I met Joe Welinske and started blabbing about my love of documentation wikis. There was probably a lot of arm waving and even a bit of in-place leaping about. Joe quickly suggested that I speak at the next WritersUA conference. I remember silence. I probably went pale. But I must have said yes, because within a few months I found myself on stage. To my absolute astonishment, my presentation went reasonably well. Since then I’ve presented sessions at a few conferences, and I enjoy the experience more each time.

At work, our team has decided to investigate public speaking as a way of sharing our experiences with others and of learning from others too. I tweeted about this during a #tcchat on Twitter, and Andrew Frayling recommended the book, Confessions of a public speaker, by Scott Berkun. Andrew is right. It’s good.

The terrors of public speaking

"Confessions of a public speaker" by Scott Berkun

One of the very first things I learned from Scott’s book is that fear of public speaking is a good thing. It’s your body’s way of preparing for a challenge. Without it, how would you cope when “a legion of escaped half-lion, half-ninja warriors fall through the ceiling and surround you, with the sole mission of converting your fine flesh into thin sandwich-ready slices”? (Page 16.)

Now, that may sound a bit of a stretch. But think again. Towards the end of the book is a set of stories of the situations some hapless speakers have faced. Dan Roam was on stage in Moscow when “six balaclava-hooded and heavily armed OMON troops (Moscow equivalent of a SWAT team)” burst in, grabbed an audience member and marched out again. (Page 184.) That story makes the average tech comm conference seem a little quiet.

It is strangely comforting to read a list of things that have gone wrong for other speakers!

Another of the stories, called “Watch your slides”, is told by Gerv Markham. His laptop with slides, and all his other luggage, was stolen in a subway station when he was on his way to give a presentation. Since then, Gerv always takes a cab.

Gerv’s experience reminded me of what happened just before my very first presentation ever. It was also my very first trip to the United States. I took a cab from the hotel, and unwisely let the cab driver put my laptop bag in the trunk with the rest of my luggage. When we arrived at our destination, the driver jumped out, grabbed my bags before I could get to them, perched the laptop bag on top of the suitcase, and then turned round to me for his fare. The laptop fell off the suitcase with a loud thump.

When I opened the bag, I found that the laptop casing was squewed, the DVD drive was permanently jammed open, and there was an ominous rattle coming from deep inside the computer. But, wonder of wonders, it booted up and worked. So I left it like that. I didn’t even try to fix the DVD drive or straighten anything at all, until the presentation was over and I was safely back in Sydney.

So, Gerv, cabs are not safe modes of transport for presentations either.

Good solid advice

Scott’s book is full of stories, and it’s full of tips too. The advice on page 19 rings true with me, about the importance of practising your presentation thoroughly. Page 21 has some great tips about how to prepare immediately before your speech.

I loved the description of the importance of a title. It “divides the universe into what you will talk about and what you won’t”. (Page 61.) And there’s an inspiring description of the only moment when you’ll have the full attention of everyone in the room: the silence just before you start speaking! (Page 80.)

Scott reveals a mild obsession with and definite antipathy towards chandeliers. (Page 40-4.) But hey, we’re all entitled to our oddities.

The book emphasizes the importance of simplicity. This is something close to a technical writer’s heart too. On page 162, Scott explains that it is our duty as speakers to simplify and clarify our points. The audience should not be doing the hard work. We should.

Thank you Scott

Thank you for a good read! I’d like to be in a room and hear Scott speak, putting all these techniques into practice. Especially if there’s a chandelier in the vicinity.

What makes simple documentation

What makes simple documentation? Our technical writing team is asking itself this question at the moment. We’re also asking our product managers to give us examples of simple documentation, and counter examples of documents that could be made simpler. I interviewed my first PM on this topic this week: Dave O’Flynn, product manager for integration at Atlassian. His answer was so neat, concise and helpful that I decided to blog about it.

Firstly, I was impressed with the way Dave quickly and unobtrusively rephrased my question. I asked him:

How would you define simple documentation and do you have some examples of simple docs?

Dave’s reply was:

The Dragons documentation is the best of example of a complex problem explained simply.

Neat. A self-documenting reply!

Secondly, it’s cool that Dave chose the Dragon Slayer documentation as his example. Dave sat back, put his hands behind his head and gave a concise list of points about what makes those documents simple:

• They are bite-sized.
• The language is clear and simple.
• They are consistent.
• The reader starts at the top and reads down. There are no links that force the reader to branch off to other documents and then come back again.
• Each page gives you a goal, then tells you at the end what you have succeeded in doing.

That’s a very useful list. One of our team members has already applied these points to a new set of documentation she is designing. I’m looking forward to more feedback from our product managers and team members. And I’m wondering, does anyone else have any ideas about what makes a simple document?

Tweaking screenshots without an image editor

A technical writer’s nightmare! You know that feeling you get when you’re taking screenshots and something happens to mess up your scenario. You can’t go back. You can never reproduce that screenshot again. “You silly Galah,” you say to yourself, before heading out for a glass of strong hot chocolate.

There are other reasons why you may want to change the data on a screenshot. Maybe you need to remove your name, other identification or private data. Maybe you want to remove the word “beta” from the software version number.

One way to fix the data is to take the screenshot anyway, then tweak it in an image editor. But that’s so cumbersome. If only you could tweak the text before taking the screenshot!

Well, you can. Technical writers rejoice!

Enter Firefox Web Developer

Web Developer is a Firefox add-on developed by Chris Pederick. Its website says that it also works in Google Chrome. When you install the add-on into Firefox, you get a new toolbar across the top of the browser window. It offers a number of very cool options. Here is just part of the toolbar, with the “Miscellaneous” option expanded.

Web Developer toolbar

It’s that “Edit HTML” option that’s useful for tweaking screenshots before we even take them.

Take a look at the page below. It says that the last editor of the page was one Sarah Maddox.

The page untouched

Let’s assume that my scenario demands an editor named Beetlejuice. I open Web Developer’s “Miscellaneous” menu and choose “Edit HTML”.

Choosing the "Edit HTML" option

The Web Developer panel opens at the bottom of the window. I search for the text “Sarah”.

Searching for the text to replace

Then I type in my replacement text, and it appears on the page as I type. Magic: the last editor of the page is now Beetlejuice.

Beetlejuice is now the last editor

When I refresh the page, it will return to its proper state. The change is only in my browser, not on the server and not visible to others who view the page on their computers.

Firebug and others

Firebug is another Firefox add-on that will do the trick. It is a little more heavyweight than Web Developer, and can slow down the response from the websites. On the other hand, I found it easier to get a screenshot of the entire window, including my changes, when using Firebug. In Web Developer, my changes disappeared each time I closed the HTML panel.

To use Firebug:

1. Install the Firebug add-on into Firefox.
2. Click the little bug at bottom right of the window. The Firebug panel opens at the bottom of the browser window.
3. Click the pointer icon, second from the left at the top of the Firebug panel.
4. Move your mouse pointer across your screen. Firebug will draw lines to highlight the various UI elements. Click when it highlights the bit you need to change.
5. Make your change to the HMTL in the Firebug window.
6. Take your screenshot.
7. Click the bug to close the Firebug panel.
8. Refresh the page. Firebug only changes what the browser displays.

I’m sure there are more tools that can do the same thing in Firefox, as well as in Internet Explorer and other browsers.

Food for thought

Hmm. Thinking of the wider implications: Anyone can write anything on a website, take a screenshot, and make it look as if the website owner wrote it.

You silly Galah!

A Galah near Sydney, Australia

“You silly Galah!” Australians say that, usually with affection, when someone does something stupid. I wonder how the expression arose. Why would you ever call something silly, when it’s so lovely?

Book review – Practical JIRA Administration by Matt Doar

Two great JIRA books in one month! I’ve just finished reading Practical JIRA Administration by Matt Doar. Recently I posted a review of JIRA 4 Essentials by Patrick Li. The two books complement each other very well. Patrick’s is a step-by-step guide to setting up your first JIRA site. Matt’s book brings you all the best practices collected and refined by a JIRA toolsmith of many years’ standing. If you think you know JIRA, get Matt’s book.

Matt Doar is eminently qualified to write this book. He knows JIRA inside out. He writes plugins to extend JIRA functionality, runs a software tools consultancy called Consulting Toolsmiths, and is a frequent contributor to the Atlassian documentation wiki. Matt and I have bumped into each other a few times, in the flesh and on various wikis and forums. He is an all-round good guy. He drops nice comments on our documentation and took part in our recent doc sprints, where he dubbed himself Matt “Galaxy” Doar.

What is JIRA?

JIRA is an application developed by Atlassian to help people track issues and manage projects. It is a web application that you can download and install on your own server. If you prefer, you can use Atlassian’s software-as-a-service offering of JIRA, which means that you get a JIRA site hosted on Atlassian’s servers. People use JIRA for various types of project, including software development, disaster management and help desks, to name just a few.

Practical JIRA Administration, the book

The book is published by O’Reilly Media, so of course it has a creature on the cover. Matt’s book got the chickens! These particular birds are Cochin chickens (Gallus domesticus) as the book’s colophon informs us. Nice. There’s a forward by the two Atlassian CEOs, Scott Farquhar and Mike Cannon-Brookes. Three of the technical reviewers are Atlassians, and one is an Atlassian partner.

The book is easy to dip into. If you like, you can read the sections completely independently of each other. Dive straight into the one you need. Matt has based the content on the questions that people ask him most often. The information applies to JIRA version 4.2.4, which Matt specifies nice and clearly on page xi.

I love the title of the last chapter: Jiraargh! Frustrations

Highlights for me

Everyone will find something different in this book, depending on their use of JIRA and the aspects that they are finding tricky. Here are some of the good things that struck me.

Hints and warnings. There are notes scattered throughout the book. For example, chapter 2 pinpoints the distinction between the “Resolved” status, the “Resolution” field and the “Resolution Date” field:

Adding a resolution named “Unresolved” to the system Resolution field is a bad idea, because since the Resolution field now has a value, the issue will still be treated as resolved by the standard JIRA gadgets.

Right now, you’re probably saying to yourself, “Huh, I didn’t think of that!” The book is full of that kind of moment.

Further reading. A section at the end of every chapter points to the relevant pages in the Atlassian documentation, useful plugins, books to read and people to contact. These are valuable pointers.

JIRA schemes. Chapter 3 tackles the complex notion of schemes in JIRA. The overview on page 11 explains the concept:

A JIRA scheme is a collection of configured values that can be used by more than one JIRA project.

I like the way Matt has divided schemes into two sets, the simple and the complex. The three complex schemes depend on the issue type (page 17). That’s a good explanation to hang on to as you dive deeper into scheme configuration. I also like the practical guidelines Matt gives on managing and documenting your schemes (pages 21-3).

Site-wide and project-specific settings. It is useful to know which settings affect the whole JIRA site, and which settings you can vary for each project. Matt gives a concise summary of just that distinction on pages 25-6. The chapter, JIRA as a Platform, goes on to show us how to configure JIRA for an example project: a project that is very different from the existing project on the supposed example JIRA site. Matt’s example is an accounting department that needs custom field types and wants to make some of the information visible to accounting team members only.

Workflows. Chapter 5 introduces workflows, one of the most useful features of JIRA. After a brief overview, Matt gives a detailed description of designing your own workflow from scratch. The idea is to build the workflow without copying it from JIRA’s default workflow. Page 36 has some useful tips about why you would want to do that. In this chapter Matt’s JIRA expertise really shines.

Remote access to JIRA. Chapter 8 gives a succinct overview of the various methods you can use to access JIRA data other than via the user interface: Email, SQL queries on the database, SOAP API, REST API, XML, RSS feeds, and two command line interfaces.

Yes, and then chapter 9: Jiraargh! Frustrations. Matt describes some aspects of JIRA that frustrate administrators, and some common problems that occur when administrators do not configure JIRA properly. The best thing is that Matt gives advice on how to avoid such frustrations. It is all very practical, living up to the title of the book. For example, take a look at page 66, where the frustration under discussion is “The field’s description may be missing or misleading“. Matt’s advice to administrators is:

Don’t accept a request for a new custom field unless it comes with a succinct and clear description of what the field is intended for. Then use that as the field’s description.

Book details

Practical JIRA Administration, by Matthew B. Doar, June 2011. ISBN 978-1-4493-0541-3. Details are on the O’Reilly Media website.

TL;DR: The book is a carefully compiled collection of best practices from a JIRA expert. It’s as if Matt sits you down by the fire and says, “Let me tell you what really matters about JIRA”. It’s the birds and the bees talk, for JIRA!

OT: Hey Matt, you can buy chocolate Galaxy pie at the Chocolate Room in Sydney. Just letting you know.