Transcript
The Australian and New Zealand Journal of Technical Communication
Issue 34
ISSN 1832‐0120
February 2015
Learning Keyboard Shortcuts Writing for Software Developers Training and Certification Scientific Rigour in Plain English Guidelines Useful Apps for Ubuntu Metrics that Click with Management Bug Trackers are not just for Bugs Head‐up Displays Southern Communicator is a joint publication of:
1
Contents 2
From the Editor’s Desk Sue Woolley gives us an outline of what we can expect in this issue of Southern Communicator.
3
Foreword Ana Young gives an insight into her career as a technical communicator.
4
Learning Keyboard Shortcuts Jacques Raubenheimer gives us some handy tips for learning and remembering useful keyboard shortcuts.
6
Writing for Software Developers Swapnil Ogale describes his first experiences of writing documentation for software developers.
9
tekom Technical Communication Training and Certification Dave Gardiner shares his experiences studying for certification through one of the most prominent technical communication training organisations.
11 In Praise of Scientific Rigour in Plain English Guidelines Judy Knighton replies to Geoffrey Marnell’s article, The Word Count Myth, published in the October 2014 issue of Southern Communicator. 12 Geoffrey Marnell replies… 13 Ubuntu: Is it your Favourite OS Yet? Alex Timanyuk follows up his article about Ubuntu in the October 2014 Southern Communicator with information on some of the useful apps he has found. 15 Metrics that ‘Click’ with Management Maxwell Hoffmann from Adobe shares strategies on how to cost-justify time-saving authoring in terms that management can relate to. 17 Just my Type by Simon Garfield Book review by Rhonda Bracey… A great read that I highly recommend. 19 Bug Trackers are not just for Bugs David Stephensen shows us how to use a simple issue tracker for, well, keeping track of issues. 24 Head-up Displays for Technical Communication Tony Self challenges us to look to a potential future for technical communication.
Editorial team:
Sue Woolley, Janet Taylor, Julie Delandro, Howard Silcock and Samantha Jones.
Final proof reader:
Steve Moss.
Copyright:
Articles remain the copyright of the author.
Cover design:
Mike Moore.
Disclaimer:
The views expressed in articles in this journal are not necessarily those of the editors.
Contact:
Send any contributions, letters, subscription or advertising queries to
[email protected].
Southern Communicator
Issue 34, February 2015
2
From the Editor’s Desk Sue Woolley gives us an outline of what we can expect in this issue of Southern Communicator. Using keyboard shortcuts for regularly-used functions is certainly quicker than using the mouse, and can potentially help with preventing repetition strain injuries. Jacques Raubenheimer gives us some very useful tips on how to learn and remember keyboard shortcuts. I recently returned to using an authoring package after several years of using Word to develop documents. I found that I was quite slow, and was going home with a sore shoulder and neck from too much mouse work. After reading Jacques's article, I was reminded of all the keyboard shortcuts I had set up in the past to speed up the writing process and reduce use of the mouse. Good timing for me, I hope it is for you too. Is writing documentation for software developers very different to writing end user content? Swapnil Ogale has the answer and explains the differences in his article. He tells us the process he followed and gives us some things to
watch out for when writing for software developers.
up that article with a description of many useful free apps he has found.
Last year, Dave Gardiner looked around for formal training in technical communication, and decided to study for the tekom certificate. tekom is the German technical communication society, and they offer a series of modules (in English) leading to certification in technical communication. Dave shares his experience of the certification process − and the outcome.
Have you been in the position of trying to justify the use of an authoring tool to your manager? The need for a dedicated authoring tool is a difficult concept for non-writers to grasp, especially as most managers consider that they have already purchased a perfectly adequate authoring tool: Microsoft Word. Maxwell Hoffman from Adobe shares some strategies for cost-justifying the purchase of a purpose-built authoring tool: FrameMaker. Although the article uses Adobe FrameMaker as an example, the method he describes can be used for any authoring software.
In the last issue of Southern Communicator (October, 2014) you may remember that we published an article about sentence length by Geoffrey Marnell: Does Length Matter? It has certainly sparked some very interesting discussions! Judy Knighton gives us her view of some of Geoffrey's arguments. We also gave Geoffrey the opportunity to reply. As an aside, Geoffrey has written a book − Correct English, Myth or Reality, which we will be reviewing in the June issue. Last issue, Alex Timanyuk explained how much fun he was having after swapping from MS Windows to the Ubuntu operating system. He follows
David Stephensen is a great fan of issue tracking and uses one for all sorts of tasks, be it garden renovation, home improvements or to help his clients. David describes a free issue tracker and what you can expect if you use it for recording tasks, issues, meetings or audits − or even its intended purpose: assisting with continuous improvement and documentation development. Tony Self challenges us to look to a potential future use of technical communication when he discusses HUDs (Head-up Displays).
Housekeeping
Happy reading!
Submission guidelines
Articles
Advertising
We welcome articles on all aspects of technical communication.
The author’s biography is printed at the beginning of the article so that you can easily see whether the author is affiliated with the product or service they are writing about. You can then make your own decision about whether the information in the article is of interest to you.
Advertising rates: Full page: AU$200, Half page: AU$100 Quarter page: AU$50 Business card size: AU$25.
Distribution
Next issues and deadlines
Please submit articles following the ‘Contributor’s Guidelines’, obtained from
[email protected] Contributors are responsible for obtaining permission to reproduce any third-party copyright material used in their articles. Articles may be edited for space considerations or to meet other publication requirements. When submitting an article, please include a short biography and photograph of yourself.
Issue 34, February 2015
Southern Communicator is published three times a year. If you are a member of TWIA or TCANZ, you receive this journal as one of the benefits of membership.
Advertisements will be clearly marked. The author of the advertisement will be responsible for the accuracy of the content. Direct advertising enquiries to:
[email protected]
July 2015 Deadline June 12. November 2015 Deadline October 9. March 2016 Deadline February 13.
Southern Communicator
3
Foreword Ana Young gives an insight into her career as a technical communicator. As a technical communicator of many years, I am often asked how I started in this profession. Like many others, I didn’t start as a technical communicator – I fell into the profession in a round-about manner. To be able to graduate in Applied Mathematics, one of the many things I had to do was to write a few programs, some of them using languages that people have forgotten ever existed. That introduced me to the wonderful, weird, and challenging world of programming. So, after graduation, the obvious choice was a role in IT. A few years and programs later, I started working at a vendor company and was introduced to the equally challenging role of keeping customers happy. Part of that role included ensuring customers had technically correct manuals, and were provided with the necessary training. And that introduced me to technical communication and training. I loved both and soon realised that I would rather write and present training, than try to figure out why a particular piece of code had decided to stop working or was not behaving as it should. The move to technical communication was not easy. For starters, my salary dropped an
enormous amount. Still, the fact I was doing something I really liked made me carry on in the profession. (After more than 20 years I am still paid far less than I would be had I stayed as a ‘techie’.) The life of a technical communicator has many challenges; one of them (maybe even the biggest one) is not being given the ‘value-add’ recognition that our work provides to a product. After all, who needs a specialist to communicate when we all go to school and learn how to write? Years of experience has (sadly) taught me that when companies resize/reorganise/restructure (select the politically correct word of your choice), the first roles to go are (in no particular order) testers, trainers and writers – the so called ‘least value-add’ roles. So why am I still here? Well, believe it or not, I love what I do. I still find being able to explain in very simple terms something that is technically very complex, a very challenging and rewarding experience. Add in the changes in work environments such as working in Agile, and the challenge is even more rewarding. And because I still work in IT, I still need to keep some technical skills and keep informed about the latest in products being used: really the best of both worlds. And now I have taken on yet another challenge: being the president of the TWIA, hopefully
what will become the Australia-wide society representing the technical communication profession. Why did I take on this challenge? Basically because I am passionate about what I do and believe that if we can get together as a whole, we can achieve what I believe we are still missing: the recognition that our profession rightly deserves. I am not alone. TWIA was formed because the two ASTCs felt the same, and everyone in TWIA's committee wants to achive this. But we cannot do it alone. I am counting on all of you to help in this quest. Can I urge you to help spread the word (ACT, NSW, Vic, Australiawide). We need your help in a number of ways: ask people you know in the profession to join or rejoin the society (we now have a retiree's membership), write articles for the newsletter or the Southern Communicator, present at the conference or submit your idea for the conference's theme, ask your company to host a meeting of members in your state or city, and so on. In other words, raise our profile as well as help us to promote and make the society work for you and all Australian technical communicators. I hope to see and meet you at this year's conference.
Back Issues of Southern Communicator Every issue of Southern Communicator, from Issue 1 onwards, is available on the TCANZ website, members’ area. To find out more, go to accessing Southern Communicator on the TCANZ website. If you have already set up your account and logged into the website, you can go directly to the Southern Communicator Journal page. Drill down on a year to see the tables of contents and links to the PDF copy of each issue.
Southern Communicator
Issue 34, February 2015
4
Learning Keyboard Shortcuts Jacques Raubenheimer gives us some handy tips for learning and remembering useful keyboard shortcuts. Do you use keyboard shortcuts? If your answer is “oh no, I can never remember them”, then you aren’t alone. You probably know that you’d be more productive – and maybe ward off the threat of repetitive strain injury – if you could just learn to use them! But the thought of learning all those key combinations can be daunting. Maybe you even tried it once and got overwhelmed. In this article I’ll describe another approach to learning keyboard shortcuts. More accurately, I’ll describe the system I use to teach myself shortcuts – and I am still continuously expanding my vocabulary of keyboard shortcuts. If you find what I write below useful, this topic is discussed in greater detail 1 in my book on Word, together with many other topics that you might benefit from. First up, how not to learn keyboard shortcuts: Don’t search for a list and try to commit it to memory. This fails, because firstly we are overloading our brains with too much information in too short a space of time (any student can verify this three weeks after an exam). Secondly, we are dealing with the list as an abstract thing, and not relating it to our use. My own experience has been that a very simple discipline, which I will get to shortly, has worked very well for learning keyboard shortcuts. Before that, though, it is useful to examine how we discover keyboard shortcuts. Yes, lists are useful for that – every time I see an article on keyboard shortcuts, I make certain that I read it (I just picked up a new Excel keyboard shortcut this week in that manner). Second, we all, or at least those who type as inaccurately as I do, have had the experience of pressing something on the keyboard, and seeing something go haywire, such as when we want Shift+R for an uppercase R,
Issue 34, February 2015
but hit Ctrl+R and right-aligned our paragraph instead. Normally we’d just undo (Ctrl+Z), but I mostly take some time to see if I can figure out what I just hit – I will sometimes undo and try to recreate the keyboard shortcut with what I thought I was typing. I will also evaluate whether this keyboard shortcut is useful for me – if not (the keyboard shortcuts in Word for Danish characters are some that, no offence to the Danes, I hope I never have to use), then I just forget about it and carry on with my life. If it does appear to be useful, then I will set about learning it. Also, it pays to be observant. It amazes me that people look at menus, and never notice the keyboard shortcuts listed in those menus. Of course, since Office 2007, the Office keyboard shortcuts are displayed in better-hidden tooltips – yet another way Microsoft seems intent on de-cluttering by dumbing down. One other note before I get to the learning bit: some keyboard shortcuts are system-wide – meaning they will either work on the OS level, or will work for almost all programs known to man (if you will excuse the exaggeration). Examples are Ctrl+C for Copy, Ctrl+P for Print and Ctrl+S for Save. Some are, for want of a better term, platform-wide, such as Ctrl+H for Replace in all of the Microsoft Office programs, while Ctrl+R does the same in many other programs. And some are programspecific, like Ctrl+Alt+M for a comment in Word, which is Shift+F2 in Excel. If I am working in a new program, I will, after having duly saved my work, freely experiment in that program with keyboard shortcuts that I believe would work there, specifically those keyboard shortcuts that are in the first two categories I mentioned. I’ve never had a computer meltdown as a result of this (yet!), and it gives me, so to speak, more bang for my buck for the effort of learning keyboard shortcuts.
Dr Jacques Raubenheimer is a lecturer in biostatistics, a research consultant, and also a Microsoft Certified Trainer and a Microsoft Office Specialist Master Instructor. He has authored a comprehensive book on Microsoft Word:
He maintains a set of extension tools for Word: http://insight.trueinsight.za.com/ word and lives in Bloemfontein, South Africa.
So, how do we learn keyboard shortcuts? Still not there yet…. Some keyboard shortcuts are mnemonic: Ctrl+B for Bold, Ctrl+I for italics, Ctrl+C for Copy – and, on that point, notice the position of the X,C,V keys on a qwerty keyboard, and remember Cut, Copy, Paste – and, in Word: Ctrl+L for Left alignment, Ctrl+R for Right alignment, and Ctrl+J for Justified alignment.
Southern Communicator
Unfortunately, not all keyboard shortcuts can be mnemonic: Ctrl+C is already taken so Centre alignment in Word becomes Ctrl+E. Obviously, mnemonic keyboard shortcuts are going to be easier to remember, but we need to go further. So, how do we learn keyboard shortcuts? Firstly, one or two at a time. This overcomes the first mistake I noted at the start. Sometimes I will do a handful at a time. For example, when I discovered various commonly used number formats in Excel with Ctrl+Shift+1 (Ctrl+!), Ctrl+Shift+2 (Ctrl+@), Ctrl+Shift+3 (Ctrl+#), Ctrl+Shift+4 (Ctrl+$), Ctrl+Shift+5 (Ctrl+%), Ctrl+Shift+6 (Ctrl+^) – although I never use the last one in my line of work. But when I do teach myself a whole bunch of keyboard shortcuts, there will be some relation between them, as in the list I just showed here. Secondly, we want to relate it to usage, thus overcoming the second mistake mentioned. Allow me to explain, because here I am finally coming to that little discipline that I hinted at. For example, this week I learned that Ctrl+6 hides all objects in an Excel worksheet. If I didn’t get that 2 from a list (I did, in this instance ) then I will make a note of it. Now I don’t work with objects in most of my sheets, so it may be two or three weeks before I get an opportunity to use that one. By then, I will have forgotten it. So three weeks from now, most people think to themselves: “What was that keyboard shortcut for hiding objects again? Arrghh. Can’t remember it. Ah well, that just proves that this keyboard shortcut stuff is a load of junk. I’ll take my mouse, click Home | Find and Select | Selection Pane, and then click on Hide All.” What I do, in contrast, is use this little discipline: I stop, go back to my list or
Learning Keyboard Shortcuts 5 note, look the keyboard shortcut up, and then use it. This process of using it activates a second memory channel 3) (muscle engrams , over and above the cognitive memory process. We all use this, we just don’t think about it. For example, I’m standing in front of the ATM to draw cash and it’s one of those days when I can’t remember my PIN number. So what do I do? Hopefully, not pull out the little slip of paper – that everyone can see! – where I scribbled it down. I know people who have had their accounts emptied in this way! No, I make as if I’m going to type the PIN, and suddenly it comes back to me. I am using my muscle engrams to bring back the memory of what my PIN is. This is the same thing that a player of tennis or cricket (or any other sport) uses to perform their shots so masterfully. In other words, the part of my brain that moves my hand to type my PIN also remembers that action – it is a second memory channel. So when I use that with keyboard shortcuts, I am actually memorising the keyboard shortcut in two different ways: cognitively and 'physically'. In fact, even now, I sometimes struggle to recall what a certain keyboard shortcut is, but if I get behind the keyboard and make as if I’m going to do it, I can figure it out again. Now sure, that process of stopping, looking up the keyboard shortcut, and using it, does take longer than just doing it with the mouse. But it is a short-term loss for a long-term gain. Once that keyboard shortcut is mastered, I will save a few seconds every time I use it, regaining and overtaking what I have lost in looking it up once or twice. And one last thing: I know keyboard shortcuts are not for everyone. I must also confess that I am not 4 musophobic , and the mouse has its place. Some things really cannot be
done without the mouse (some programs, for example, are really not keyboard shortcut friendly) and some things, not many, but they are there, can be done faster with the mouse than the keyboard. Some things, of course, can only be done with the keyboard and mouse in conjunction (macros aside): Did you know that you can select one sentence in Word by holding the Ctrl key while clicking anywhere in that sentence? (This does sometimes trip over abbreviations, though.)
…I look the keyboard shortcut up, and then use it. This process of using it activates a second memory channel, … over and above the cognitive memory process. Keyboard shortcuts definitely do help you work faster, and keyboard shortcuts can help out in the most unlikely situations – those that you have never thought of. For example, have you ever tried working with the touchpad of your laptop while seated in a plane going through some turbulence? So much so that, in addition to keyboard shortcuts, I have memorised quite a few ribbon manipulations on the keyboard, such as Alt | JL | F | C to AutoFit a table in Word – I defy you to do it quicker with the mouse than I do with the keyboard. Sure, I could create a keyboard shortcut for that and do it seven split seconds faster, but typing that string is so quick, I hardly see the need. The question then becomes twofold: How many keyboard shortcuts do you know now? More importantly, how many keyboard shortcuts will you know a year from now?
References 1 http://insight.trueinsight.za.com/word/dissertation/book 2 http://www.databison.com/so-how-many-of-these-excel-shortcuts-do-you-know-punk 3 Go look it up if you’re curious. 4 Go look it up, although I am twisting the word beyond its original intention.
Southern Communicator
Issue 34, February 2015
6
Writing for Software Developers Swapnil Ogale describes his first experiences of writing documentation for software developers.
Overview
Project background
After writing content for end users on a number of projects, in 2013 I was offered two opportunities to create content for developers, which I gladly accepted because it is nearly impossible to get this kind of experience outside a real project.
The first project I worked on was a Business Intelligence (BI)/Data Warehouse project for a public health organisation. My role on the project was to:
This article describes how I went about creating the content and lists a few things to watch out for while creating developer documentation.
What is developer documentation? There is no single definition for developer documentation; it can mean different things to different people. It can mean architecture or network documentation, API (Application Programming Interface) documentation, process documentation or design documentation.
How is it different to user documentation? Developer documents differ from user documents in the following ways: 1. Developer documents are almost always more technical than user documents. When creating developer documents, the writer can almost always assume a high degree of technical knowledge, both about the tools and the product itself; giving the developer documents a distinct flavour and tone. 2. Developer documents are aimed more at the process and/or tools used to create and maintain a product than how to use the product itself. 3. While user documents can often be tailored to suit multiple levels of users, developer documents are usually created and delivered in one standard format.
Issue 34, February 2015
gather information from various developers working on the data warehouse analyse this information transform this data into a reference or knowledge-base that could be used to understand the: data warehouse components logical aspects of deriving the data from multiple sources flow of information across multiple systems.
About the same time, I was also working with a geographically dispersed team of internet media individuals to create a knowledge-base of developer and user documentation. The product was a web-based, aggregated Internet TV streaming channel. The idea behind the developer documentation was similar to the data warehouse project: the need for a repository of knowledge that documents development efforts, processes and tools for the web product.
Swapnil Ogale has over eight years’ experience working as a technical communicator across a number of industries such as IT, finance, utilities, education and public health. He has a Graduate Diploma in Technical Communication from Swinburne University and a Masters of Business in Information Systems from Victoria University. He is the current organiser of the Melbourne Flare User Group, the first of its kind in Australia.
The documentation process Research, research, research Before I started gathering information from the developers, I familiarised myself with the tools and technologies the developers used, so that I could understand what they were trying to achieve with these specific tools. It was a great experience learning about the Integrated Development Environment (IDE, in this case, Visual Studio) and database tools, code repositories, issue trackers, and BI concepts.
Southern Communicator
Writing for Software Developers 7
Having some sort of idea of the tools and concepts went a long way towards helping me to interact with the developers for the next steps.
Gathering information from developers Information gathering was the most challenging part of the content lifecycle. While developers may be the most technically knowledgeable people, especially about the tools and technology they use, they can struggle to communicate what they know sufficiently clearly for a technical writer to translate that knowledge into something everyone can understand. Developers also have their own individual way of handling code and processes and tools, so it was difficult to document one standard or consistent practice across the data warehouse processes. For example, in the data warehouse project, one developer brought data from various systems into the warehouse and wrote code to transform it internally, while a second developer transformed all the data before bringing it into the data warehouse for reporting. Developers were located remotely for the second project, making it difficult to get information in real time. Almost all the information gathering was conducted via email and instant messaging.
Creating content to cater for all learning styles The developers I worked with were highly professional and technical people. While gathering information from them, I made subtle observations about their learning styles and, more importantly, how they personally retrieved information from their documents. For example, one developer was a very visual person and drew me diagrams whenever he explained a process, so I made sure that the documents contained a lot of workflow diagrams and images to depict processes.
Southern Communicator
Another developer was happy to look up detailed information where required and just focus on a linear process, so I made sure the documents contained plenty of links and cross references. The data warehouse I was documenting was technical in nature and my documents needed to explain how various data systems interacted to transfer data for reporting and other purposes. While it was impossible (and mostly not really useful) to put in screenshots of the databases, I was able to create a number of workflow diagrams using Visio to help the developers visualise the flow of data in and out of the data warehouse.
Reviewing content Content review was another tricky part of the process, because as much as developers are reluctant to share their knowledge, they are even more elusive when it comes to reviewing content. In the data warehouse project, I was using a help authoring tool so I was able to create a few different outputs to suit developer preferences for reviewing content. In the second project the documentation was wiki-based, so it was relatively easy to get the developers to review any content, almost in real-time. I also found that given their analytical minds, the developers liked to access content in a non-linear manner, so it was important to provide a map of the content and context around individual sections. As part of the project, developers were continuously updating database tables and code to access source system data, so it was necessary to prioritise what content needed to go in once, as opposed to periodically changing information. For example, once the data warehouse table structure was signed off, it was prioritised ahead of additional data coming in from other source systems based on the organisation’s requirements. In order to accommodate this, the review
process had to be planned so that the core content could be reviewed once, whereas any additional tables would be reviewed periodically.
Publishing the developer documentation Prior to creating the developer documentation, I created prototypes to get developer feedback on the delivery and accessibility of the online content. This ensured that the developer documentation was delivered in the manner that was the most effective and useful for the developers.
Things to watch out for Based on my experiences, here are a few things to watch out for when creating your own developer documentation:
Communicate with the developers at each stage of the content development lifecycle; this ensures you always receive the latest information. Try to understand the technical concepts and terminology that developers use so that you can include this flavour in the content. Depending on the complexity of the tools involved, developer documents may take longer to create, so ensure that your progress is communicated to project managers at regular intervals.
Summary I found writing documents for developers a very enriching and fulfilling experience. While a technical communicator has to understand the product before creating user documentation, writing developer content is even more challenging because you have to research and learn about the tools and technical concepts that go behind creating a product/system. .
Issue 34, February 2015
Ensure your Help content takes off and lands smoothly on every device Upgrade to the power-packed Adobe RoboHelp 11 Now available at a monthly subscription of A$29.99/US$29.99
Call 1800 614 863 (Monday-Friday, 9am-5pm)
Adobe, the Adobe logo, and RoboHelp are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. © 2015 Adobe Systems Incorporated. All rights reserved.
9
tekom Technical Communication Training and Certification Dave Gardiner shares his experiences studying for certification through one of the most prominent technical communication training organisations. I had been looking for some formal training in technical communication, and after considering courses in the US and New Zealand, settled on the German tekom first-level certificate in technical communication. It was a good move. Delivered online by TCTrainNet (http://www.tc-train.net), the course provides training and tests for basic competencies in a range of subject areas. The training leads to certification with an exam, and is well worth the investment as an introduction for new technical communicators or as a refresher for those already in the profession. The certificate is designed for technical communicators wishing to check that their skills and knowledge are aligned with the expectations of the profession. There is also an advanced certificate on offer for experienced practitioners. On the TCTrainNet website you will see all the submodules to study, with a few of these freely accessible with a guest login to give you a taste of the training. I studied with students from Germany, Austria, India and China. The discussion forums are an excellent way to learn from others’ experiences as you respond to the training and practical tasks – you are studying with your group for several months and get to know how they do their job and how technical communication works in different industries. The course eases you into study for the first few weeks, then you plough through one sub-module each week for approximately six months. Nine main modules comprising 24 sub-modules take you through the essentials of
Southern Communicator
professional writing, layout and visual design, managing translation and localisation, online documentation, the DITA standard for technical communication, terminology management, information development, structuring and standardisation with XML, and legal requirements and international standards. You must complete all modules to qualify for the certification exam. The material is mostly theory and concepts of various aspects of technical communication. Every week there are small practical exercises to consolidate learning, such as setting up style templates in Microsoft Word, or using a trial version of the oXygen XML Editor to produce a few pages of a document with DITA markup. Each sub-module has a recorded webinar of 30 to 45 minutes to introduce the key issues of the topic – a TCTrainNet presenter speaking to a PowerPoint slideshow that introduces the submodule’s material. Then you work through the online interactive training – click through each slide, or tap on boxes, move pieces of text around to complete sentences, click on web links, and watch little animations to get to the next slide and successfully complete each week's learning notes (the interactivity keeps you engaged with the material). There are also links to a moderate amount of reading material such as TCWorld articles, websites or PDF documents that give you different aspects of the material from a practitioner’s viewpoint. After the interactive training there are one or two small exercises where you research a topic, and post your answer in the discussion forum.
Dave Gardiner is a technical communicator with expertise in XML publishing technologies, and has a background in print and ebook publishing and redrawing scientific illustrations. He has developed online help using DITA with an interactive visual user interface, and has published articles in US and UK journals. He holds the tekom first-level certificate in technical communication.
It is a great way to collaborate on exercises, compare answers and discuss alternatives. Finally, there is a short quiz to test your learning. This keeps you busy for an average of 8 hours each week that the course recommends. At the beginning of the course – for the first month or so – you wonder why you are learning theories about reading and comprehensibility and so on. But it gradually falls into place, where later modules build on the knowledge gained from the earlier ones. You need to stick with the learning because you come across some really interesting modules with XML, translation, terminology management, information development and online help. It's a good course to consolidate the experience you already have with documentation.
Issue 34, February 2015
10 tekom Technical Communication Training and Certification The international course has been developed from the Germanlanguage course, which has run for many years. The material is still very Germancentric, with discussion about DIN standards, German studies and experts in documentation. But treat this as a stepping-off point to research your own country’s practices and standards – it helps to answer each week’s exercises from your own perspective so other students gain from your experience. (Recounting your experience also helps when taking the certification exam.) You need to apply to sit the certification exam, the cost of which is included in the training.
Then you have several weeks (in my case it was three months as we all tried to settle on an exam date) to finish off exercises, do quizzes you missed and revise the training material (and there’s lots of it). The certification is held online with the other students and is in two parts – practical tasks and an oral exam. With the European students sitting the exam early on a Saturday morning, and me in the early evening, we were emailed two tasks in Word documents. We had 90 minutes to rewrite instructions for a machine disassembly/reassembly task, and restructure a manual’s table of contents to reflect task-based topics.
A break, then the oral exam by webcam – questions focused on definitions, concepts and hypotheses. It was an intense four hours. I got an email two days later – I passed with a ‘B’. So now I am no longer a book editor with a little technical writing experience – I can call myself a technical communicator. The certification is international recognition that says I can be a competent member of a documentation team. And it’s recognised by national organisations as professional development. tekom certification is not as hard as you might think.
P.S. Since gaining certification, I landed my first technical communication contract. In my application and interview, I cited learning from the certificate course about 'writing from the user's perspective' and ISO standards, which no doubt helped me win the job. Without this training, I think it would have taken me much longer to slowly gain experience to enter the profession.
Issue 34, February 2015
Southern Communicator
11
In Praise of Scientific Rigour in Plain English Guidelines Judy Knighton replies to Geoffrey Marnell’s article, The Word Count Myth, published in the October 2014 issue of Southern Communicator.
In a recent article in Southern Communicator, Geoffrey Marnell discusses the word length of sentences. He suggests that common recommendations on word counts of sentences ‘have never been subjected to critical scrutiny’. Dr Marnell provides some excellent reminders to anyone who believes we can reduce the craft of good writing to a series of mechanistic rules. Yes, we remember information chunks, and not words. Yes, a competent writer can write a long sentence that is far clearer than a poorly written short sentence. And, yes, any readability formula that can be implemented by a computer can only ever provide a poor substitute for the experience of a real reader. However, I take issue with the article on several points. First, the article sets up a straw man. Starting with the recommendations made by plain English specialists for an average word count of 15 to 20 words, the article skips briefly past the fact that this is one element in a number of recommendations. For the remainder of the argument, word count is treated as a single, stand-alone, all-important rule, making it an easy target. Dale and Chall (1948) define readability as: "The sum total (including all the interactions) of all those elements within a given piece of printed material that affect the success a group of readers have with it. The success is the extent to which they understand it, read it at an optimal speed, and find it interesting."
Southern Communicator
The plain English movement has never said "Write short sentences and you will be clear." Second, to say that recommendations on sentence length are not based on careful empirical research is to ignore 121 years of research, starting with Sherman in 1893. The first readability formula was developed in 1928 (Vogel and Washburne). Sentence word count was one of four factors found to correlate (to 0.845) with reading scores. Since then, many refinements of this original formula have been scientifically tested. In 1935, Gray and Leary established that average sentence length in words has the highest correlation to how hard a text is to read, while percentage of easy words has the highest correlation to how easy the text is to read. This, by the way, means that Dr Marnell’s 11-word sentence is not a useful test of reading difficulty. Testing two short sentences against one another is a good way of showing that multi-propositional sentences are harder to read. It does not tell us anything about the difficulty of reading long sentences. Though critics of readability formulas have been legion since at least the 1960s (when the formulas first began being used in the commercial world), research shows that their scores correlate well with comprehension difficulty. Some critics have complained that the formulas were developed for children. The records show many popular formulas were developed for and tested with adults.
Judy holds a Masters in Communication and is accredited in public relations through the Public Relations Institute of New Zealand. As a writer and editor for a broad range of government and private-sector organisations, she has applied her clear writing skills to topics as diverse as insurance, climate change, income tax, genetics, finance, local government, and health. Judy has been a member of Write Limited’s plain English consulting team since 2009 and a technical communicator since 1986.
"Research eventually established that the two variables commonly used in readability formulas – a semantic (meaning) measure such as difficulty of vocabulary and a syntactic (sentence structure) measure such as average sentence length – are the best predictors of textual difficulty" (DuBay, 2004).
Issue 34, February 2015
12 Geoffrey Marnell replies… Third, the article includes a quote by Kintsch dated 1975. Beginning in the 1970s, Kintsch and associates claimed that cognitive issues were more important than structural issues.
By 1981, he had changed his mind, saying "… [readability] formulas are correlated with the conceptual properties of text" (Kintsch and Miller, 1981). He found that vocabulary and sentence length are the strongest predictors of difficulty.
I wholeheartedly agree with Dr Marnell that the guidelines we offer to writers must be based on evidence. I commend him for raising the issue, even though I find the example he offers to be unworthy of his defence.
References Dale, E, and J S Chall. ‘A formula for predicting readability’. Educational Research Bulletin (21 January and 17 February 1948) 27: 1–20, 37–54. DuBay, W H. The Principles of Readability. Costa Mesa, CA: Impact Information, 2004. Gray, W S, and B Leary. What Makes a Book Readable. Chicago: Chicago University Press, 1935. Kintsch, W, and J R Miller. ‘Readability: A view from cognitive psychology.’ In Teaching: Research reviews, (ed) D E Newark International Reading Association, 1981. Sherman, A L. Analytics of Literature: A manual for the objective study of English prose and poetry. Boston: Ginn & Co., 1893. Vogel, M, and C Washburne. ‘An objective method of determining grade placement of children’s reading material’. Elementary School Journal 28 (1928): 373–81.
Geoffrey Marnell replies… At the outset let me thank Judy for extending what is an important debate. However, as a criticism of my own paper, her comments mostly miss the mark. First, it can hardly be claimed that I am jousting at straw men when I preface my paper with quotations from contemporary commentators espousing the importance of word count (one of whom calls it a “fundamental” consideration in writing well). Moreover, accepting that readability is multi-faceted (as I do) does not mean that it is a fallacy to criticise the importance of any one alleged facet. (Is a physician’s criticism of the value of a particular vitamin a straw man fallacy simply because good health requires a range of vitamins?) Second, Judy creates the impression that my paper was an attack on Plain English. It was not. (Is, say, a scientist’s criticism of the views of fellow scientists an attack on science?) Third, the validation correlations cited by early researchers have been challenged many times (with some experiments finding a correlation between readability scores and comprehension scores
Issue 34, February 2015
as low as 0.13: see chapter 6 of my book Correct English: Reality or Myth?). Anyway, I did not claim that there is no correlation between word count and readability. In general, long sentences are difficult to read, so some correlation is to be expected. But my point is that the difficulty is owed more to exceeding the chunk limit of our short-term memory than to the number of words. Fourth, I did not suggest, or even imply, that readability formulas were developed for children. (Children didn’t even get a mention in my paper.) Fifth, I must invite Judy to re-read the Kintsch and Miller paper of 1981. Contrary to her suggestion, Kintsch does not recant the material in his 1975 paper that I used to explain my experimental results. Indeed, he repeats a good deal of it. And nowhere in the paper does he say that vocabulary and sentence length are the strongest predictors of difficulty. (Sadly, Judy is merely repeating, word for word, the sloppy research of William DuBay who, in the book she mentions, makes the same erroneous claim.) Kintsch even
states that “predictions from these formulas are often inaccurate”. Further, “their empirical accuracy is limited, and, perhaps more importantly, they are of virtually no use in guiding the composition of texts that are easy to read. [Rather] the measurement of the conceptual complexity of a text inevitably requires conceptual tools and measures which traditional readability formulas lack”. The conclusion of the Kintsch–Miller paper emphasises the “tentativeness of current research” and that since “comprehension, and therefore readability, is a complex, multilevel process … a battery of tests will be necessary [making the measurement of readability] far more difficult than computing a Flesch score”. Finally, Judy ends by implying that my paper was not based on evidence. But the centrepiece of my paper – which she ignores – is a report on an experiment. Data was provided that supports the conclusion. You can only claim that such data is not evidence if you can show contrary data. None is given.
Southern Communicator
13
Ubuntu: Is it your Favourite OS Yet? Alex Timanyuk follows up his article about Ubuntu in the October 2014 Southern Communicator with information on some of the useful apps he has found. “Ah, Ubuntu! You are my favourite Linux-based operating system.” Sheldon Cooper, Big Bang Theory. Wikipedia's article about the Ubuntu operating system states: “As of January 2009, almost half of Google’s 20,000 employees used a slightly modified version of Ubuntu.” And, if you, my fellow geeks, are big on security, you'd be thrilled to know that in January 2014, the UK's authority for computer security, CESG, reported that Ubuntu 12.04 LTS was "the only operating system that passes as many as 9 out of 12 requirements without any significant risks." Now away with ice-breakers and down to brass tacks! This is a follow-up article, and its sole purpose is to share with you the goodies and lessons that this humble author has learned from using the Ubuntu operating system (14.04 LTS). This is not an infomercial, Canonical Ltd pays me nothing, so it is as bias-free as these articles come.
Installation options Firstly, getting back to its installation options, Ubuntu offers a choice between a regular and an encryption-based installation mode. I opted for the encryption one (just in case my laptop is lost, and my HDD is extracted). However, when I had to re-install Ubuntu, I was faced with a fair bit of trouble trying to decrypt my data, even though I remembered the log-on, and, of course, the encryption password. Do tread carefully in the encrypted installation territory! Another lesson I learned the hard way was that enabling the display of the files hidden by default, and then accidentally deleting them, was a major mistake. Basically, the
Southern Communicator
reason I had to re-install Ubuntu was that I had accidentally deleted hidden files, and, sure enough, it just would not start.
Apps A huge range of apps seem to run well on Ubuntu. You can download and install all of the apps mentioned in this article with literally one click from the Ubuntu Software Center icon displayed on its taskbar. And they are all free!
Skype Skype runs fine, especially with the awesome Skype Call Recorder app. As you know, Skype does not provide a voice-recording feature of its own, but with the recorder app you are well-equipped to elicit and record the mind-dump from any SME – anywhere!
Structured, DITAcompliant authoring If you author structured, DITAcompliant content, the latest oXygen XML Author runs without a hitch, too. If you also commit, or upload your content to a cloudcontrolled database, then Git Cola might be the answer to your prayers. I used only the command line Cola, but a GUI is available and presumably works fine. The Git Cola app transfers the topics authored in oXygen running on Ubuntu to a version-controlled repository in the Cloud. It is a relatively straightforward and easyto-use app.
Alex Timanyuk is currently a freelance technical communicator and InfoPinions.com owner/operator, Alex has been heavily involved in the IT and software development sectors for over 12 years (and he can still remember what Windows 95 looked like). Originally from Ukraine, Alex worked as a technical communicator for a number of companies in Eastern Europe, and for four corporations since arriving in Australia. His primary interest is structured authoring and information development, for example, DITA/XML, plus UX concepts. Alex was formerly an ASTC (NSW) committee member.
Keyboard shortcuts If you still have trouble remembering the equivalents of your Windows shortcuts, press and hold the Windows Start button on your keyboard (referred to as the Super key in Ubuntu). The list of
Issue 34, February 2015
14 Ubuntu: Is it your Favourite OS Yet? Ubuntu shortcuts will pop up in a split second.
Illustrations Illustrations are now becoming an integral part in the life of a technical communicator, and Ubuntu comes with its own screenshot app. It is acceptable, but if you want to produce screencasts, or need the capability to record sound from speakers and a mike, then look no further than Kazam. Also, the Gimp image editor is useful if you need to tinker with screen-shots.
Security For those after a bit of extra security, Gufw Firewall is as userfriendly as a firewall can theoretically be. It's probably the most user-friendly one that I have seen.
Sharing files Sharing or downloading files over the Internet? There is a built-in, sleek and reliable, Transmission
BitTorrent client. Exercise caution though, as there may be legal implications to downloading files – everyone should realise that most of the content on peer-to-peer networks is illegal.
Notes®, are really useful. There are lots more out there, of course.
Zip files
What about music? Well, VLC Media Player happens to play back almost anything and worked well for me, and Brasero Disc Burner was okay, too.
Did I mention that you can rightclick a file, and click Compress to instantly zip it into .zip, .tar, .jar, and lots more formats? You can also use Ubuntu's Super key on your keyboard, plus any number from 1 to 9, to launch a frequently used app pinned onto your taskbar.
Internet browser
Search filters
If you use the Chrome browser, then its Chromium counterpart would do almost the same on Ubuntu, apart from the capability to edit files stored in SharePoint. In case you wondered if there is any connection between the two, Google releases the majority of Chrome's source code as an opensource Chromium project.
Being nostalgic about the now defunct Google Desktop Search, the feature that I liked most was Ubuntu's search filters. Look at the screen-shot below; it's just too easy to filter away by clicking either Files & Folders (obviously, your local content), or Google Books, Amazon, Reddit or other buttons.
Time-saving apps
Forget about Copernic Desktop Search, this feature is a sight for data-miners' sore eyes!
Music
The Alarm Clock reminder app and Xpad, a kind of on-screen Sticky
Summary This article lists just a tiny fraction of an endless pool of tried-and-true apps the open-source community has created. Still paying for your software and contributing to the wealth of the select few? Think again, switch over, give it a try – nearly half of googlers can't be wrong.
Issue 34, February 2015
Southern Communicator
15
Metrics that ‘Click’ with Management Maxwell Hoffmann from Adobe shares strategies on how to cost-justify time-saving authoring in terms that management can relate to.
It started in Mesopotamia At some point in our careers, all of us have been in the position of trying to cost-justify an upgrade to better authoring tools whose benefits seem patently obvious to all involved. Unfortunately, we also have to communicate those benefits to our budget gatekeepers, managers, who are often out of touch. I suspect this may have been an issue in ancient Mesopotamia, when early scribes had discovered a better source of clay to make their cuneiform tablets more readable. No doubt, management in those days of yore responded with, “Why can’t you just use the clay that you’re standing on?” Management, by definition, will always be somewhat disconnected from authoring tools and workflow. If they had the expertise that we have acquired, they wouldn’t have time to manage. Thus, we will always be inventing either a new language or compelling word pictures to drive our points home, and relate a new solution’s benefits in terms that our managers can understand. In this article, the mud we are standing on is Microsoft Word, and the more pliable, ‘pleasing to the eye’ mud is Adobe FrameMaker. You will find that the strategies and tools recommended for costjustifying an upgrade to FrameMaker can be used for other products as well. Read on!
Why so many of us still try to stretch Word beyond its limits Word is just there. Like water. Like the weather. It seems to be omnipresent. This has evolved over time as Word has commonly been bundled with corporate laptops and desktop computers. As a result, most of our managers feel that they’ve already paid for some software, and we should just be content and work with what we have. Unfortunately, the designers of Word didn’t really have challenging, high-volume, multiversioned technical documentation in mind when the core code of that product was developed. Word is still mainly intended as a high-end, generic office productivity tool. Don’t get me wrong. I am not trying to ‘slam’ Word or diminish its worth. I have a very few acquaintances who have achieved impressive results with Word. But it takes them quite a bit longer to achieve their goals than it takes me with the arsenal of slightly higher priced authoring tools that I use. The effort to get there via Word can also require delving into 300+ page ‘advanced’ books about Word.
A former product manager for FrameMaker at Frame Technology, Hoffmann also spent nearly 15 years working with multi-lingual production and XML publishing for Language Service Providers (LSPs). Maxwell works from a virtual office in Portland, Oregon, USA, where his hobby is identifying and collecting mid-century antiques, including vintage technical documentation. E:
[email protected] W: http://blogs.adobe.com/techcomm Tw: @maxwellhoffmann
Has this ever happened to you? Although Word has improved through the years, there are still many areas where documents or objects created with it are somewhat fragile. The following list summarises areas where I most frequently see pain points and complaints expressed in forums: •
Southern Communicator
Maxwell Hoffmann is Adobe’s Technical Communications Evangelist.
inserting or deleting section breaks adjacent to numbered
Issue 34, February 2015
16 Metrics that ‘Click’ with Management
• •
•
•
• •
•
lists or complex numbered headings insertion and editing of equations (especially editing) insertion of cross-references that point to multiple targets, for example “for more info, refer to Section 1.1 How to lay an egg on page 1.13, located in Chapter 1 All About Eggs” managing index entries that go beyond one or two levels of indent/sorting managing cross references and other links to external documents managing externally referenced graphics controlling anchored frames that must be positioned in outer margins and paginate properly in two-column layouts insertion or deletion of landscape pages in the midst of portrait pages peppered with many multi-level, numbered headings.
Chances are, if you have done any of the actions listed above, you may have discovered that more than a few steps were required to restore the integrity of your document. In extreme cases, like projects in multiple languages, just one of these issues can add up to more than a full week of your time across the year.
How much is your time worth to your enterprise? One of the key costs we incur is that of lost time and lost project opportunities. If our management insists that we continue to use Word for authoring ‘to save money,’ chances are they are not noticing how many projects we could have started or completed in the weeks of time lost to manual processes to fix issues related to items beyond the bulleted list shared earlier. Now, here is the rub. Even though we may be highly valued by our employers as technical content creators, chances are that no one is keeping track of the cost of our lost time. Many companies simply view our individual cost as an annual salary, plus benefits. Since our lost hours and opportunities are not tracked as a profit and loss line item on a spreadsheet, most managers are in denial that these issues even exist. So, let’s explore an actual spreadsheet tool we can use, that would make any manager’s heart jump with joy. And, let’s also explore ‘word pictures’ we can employ to get our managers to grasp just how much time and money is being lost.
An appealing spreadsheet summary your manager can understand In this article I am using Adobe FrameMaker as an example for the desired solution. This is not only because that is the product that I am most familiar with, but also because Adobe has created a nifty ROI (Return on Investment) calculator that can work as a model for other product solutions as well. You can find a highly versatile calculator that compares ‘per feature’ savings and losses in Word vs FrameMaker in a special microsite: www.douwriteright.com. If you scroll down to the piggy bank icon, you can click and register to use this powerful tool. See Figure 1 for an example of some of the advanced publishing challenges covered. For a direct link to the calculator, go to: http://bit.ly/10XOt2G. Note that you will need to register to use this site. You may adjust your costs per hour, the number of times you anticipate that a feature may be used. You may even set the number of events to ‘0’ to cancel out any of the categories that don’t apply to your workflow.
Figure 1. Some of the advanced publishing challenges covered by the ROI calculator
Issue 34, February 2015
Southern Communicator
Just my Type by Simon Garfield 17
Although this calculator is not designed to let you insert your own categories, you could easily change the metrics for any category and use values that fit a feature we haven’t included. Naturally, you could take this calculator as a model, and create your own, more focused version.
Exploring a new solution The FrameMaker calculator will help you discover advanced feature sets that can dramatically reduce the amount of time you currently invest in mission critical work. The calculator will also reveal some feature/solutions you may have never heard of, like ‘Object Styles,’ which enable you to globally update named graphics or anchored frames.
You will find that the strategies and tools recommended for cost-justifying an upgrade to FrameMaker can be used for other products as well.
Create compelling ‘word pictures’ for your manager
Vivid, frightening mental images (hopefully the type that lead to nightmares) are the most effective.
Sometimes, you can make the most progress in your quest for a more efficient authoring solution in those ‘little quiet moments’ with your manager. Over a cup of tea, or beverage of your choice. Ask your manager some hypothetical questions like these:
As obvious as this exercise may seem, most managers don’t view the 45 minutes or 90 minutes that you lose here and there as serious cash leaks. But, mission critical projects can die a death by a thousand cuts (or ticks of the clock.)
•
You are special, and everyone should know it
•
•
If someone smashed in three of our office windows with a cricket bat, and we were ‘heating’ our winter parking lot, what would you do? If you noticed a tiny hole in the bottom of the sugar shaker, and employees were leaving tiny white trails across the break room, how would you fix that? If you had a laser printer that jammed one out of five sheets of paper, what action would you take?
This list is potentially endless. The point is to get your manager to notice that he/she frequently fixes cash leaks, rather than lose a fortune in utility bills or sugar over a long period of time.
The calculator and word picture exercise can spawn another benefit as well; you can discover how to articulate just exactly how important your work is. We can get beyond whether our job titles, or levels on the org chart are conveying our worth. Once you’ve taken a hard look at how much time you can save your company through using an advanced publishing solution, well, it’s just hard not to feel good about yourself.
Just my Type by Simon Garfield
ISBN: 978-1846683022 eISBN: 978-1847652929
Book review by Rhonda Bracey A good friend recommended Just my Type to me and I’m so glad he did.
I particularly loved Chapter 11 (DIY) where he gave a brief overview of the days of letter stamps, Letraset, IBM golf ball typewriters, Dymo label makers and so on − almost all of which I used in the 70s and 80s and even into the early 90s before I got my first computer.
What a terrific read! The subject matter (fonts and typefaces) sounds very dry and boring, but this book is anything but. It is a delightful romp through typeface history from Gutenberg to just a year or so ago, and offers insights into some of the very human emotions associated with people who are passionate about their profession/vocation.
This book stays with you. Since reading it, I’ve really been noticing the types of fonts used for TV/movie credits, on signs, in advertising, logos….
Garfield writes in such an engaging and entertaining manner that you don’t need to know much at all about fonts to learn something from his book. He covers fonts from Arial to Zipf and many fonts in between, particularly those we see on our computers every day.
A great read that I highly recommend. Editor’s Note: I recommend that you read the description of this book’s contents which you will find on Amazon UK’s website.
See Rhonda’s very useful website at http://www.cybertext.com.au/
Southern Communicator
Issue 34, February 2015
Suite power. Sweet savings.* Adobe Technical Communication Suite 5 Five powerful software. One integrated toolkit. Now available at a monthly subscription of A$49.99/US$49.99
> _
+
+
+
+
Call 1800 614 863 (Monday-Friday, 9am-5pm)
*The full version license of Adobe Technical Communication Suite 5 retails at $1,699—which is 57% less expensive than buying all individual products separately. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners. © 2015 Adobe Systems Incorporated. All rights reserved.
19
Bug trackers are not just for bugs David Stephensen shows us how to use a simple issue tracker for, well, keeping track of issues. A bug tracker or issue tracker is a program that manages and records the life cycles of tasks and issues. In this article I’ll share with you the magic of this very simple application and how you can use free issue tracker software for a variety of tasks and workflows in a business or a project. The benefits for a business or project include:
Records of tasks, issues, meetings or audits are in a single location instead of a tangled chain of emails. No idea, request, issue or record is ever lost. There are fewer folders of documents to keep under control. Team member progress and backlog statistics are readily available.
Issue life cycle and roles An issue is basically a request for action − to carry out a task or solve a problem.
Issue statuses An issue normally moves through four colour coded statuses:
David currently works with small to medium businesses, helping them to streamline and document the way they do things, and to prepare for ISO 9001 and other certification. Previously he was a software trainer and secondary school IT teacher.
New issue − Not used, more about this later. Assigned − The Reporter asks the Problem Solver to do something. Resolved − The Problem solver believes that he or she has done the job. Closed − The Reporter is satisfied with the Problem Solver’s efforts.
There is another status for when a stakeholder is not happy after the event:
Reopened − A stakeholder wants more action on the resolved or closed issue.
There are two main players in an issue:
Reporter − requests the action. Problem Solver − carries out the action.
There are two other players who might get involved:
Manager − cares about smooth running of the issue system. Stakeholder − cares about the issue.
This chart shows the roles in, and who changes the status of, an issue:
How it all started… A few years ago I was working for a software development company as a technical writer. I got access to their issue tracker for the rare occasions when a developer might take notice of a useability issue that I raised. I liked it and started using it for my own ‘to do’ list. Later, they asked me to help set up their quality management system for ISO 9001 certification. I saw immediately how the issue tracker could be used for continual improvement and corrective and preventive actions. This was the start of a grand love affair. Today, I have a client who uses a free issue tracker for nearly all of the workflows described in this article.
Southern Communicator
Issue 34, February 2015
20 Bug trackers are not just for bugs
Business workflows that suit issue trackers The issue life cycle lends itself to many business workflows. There are three basic types:
requests for service problems to be solved events to be recorded.
Requests for service These issues can include:
maintenance requests purchase requisitions internal orders task assignments.
The search for an issue tracker MantisBT Bug Tracker In 2009 I decided that my new client, a steel foundry, needed an issue tracker. I researched the free open source ones and settled on MantisBT Bug Tracker: MantisBT (http://mantisbt.org). It had nearly all of the commonly required features and yet was famous for being simple. It is a free, open source PHP + SQL database application with a range of compatible databases including MySQL.
Projects
1. Containing the problem.
As with all but the most simple issue trackers, each MantisBT issue belongs to a project and each project has its own configuration according to its purpose. For example, you could have purchase requisitions, quality issues and meeting minutes projects, each configured a little differently.
2. Correcting the problem.
Pages
Problem solving issues Problem solving issues include corrective actions:
3. Finding the root cause. 4. Removing the root cause. 5. Preventing recurrence.
Record keeping Although it is an unusual way to use an issue tracker, it is an ideal place to store certain records such as:
meeting minutes (with links to individual action item issues) audit reports (with links to individual findings) statements, indicating any actions that were taken documentation reviews.
Similar to most issue trackers, the MantisBT issue tracker user interface has the following basic page types:
Report issue page View issue page (including add comment form and change status controls) Change status pages − Resolve, Close, Reopen View issues page (including filter and search) Issue statistics page.
Here’s a brief overview of each page type.
Report issue page This is the basic report issue page:
Using an issue tracker for this task has these advantages:
The meeting convenor or auditor can look at the report and see immediately which items or findings have been actioned. The link in the following example is crossed out because the issue is closed.
Records are indelibly date-stamped and have a complete change history. They cannot be easily faked after the event. The status workflow for records is simpler:
Some projects require more information than the basic form provides. You can add custom fields to the report issue form to capture special information needed for the type of issue. The issue tracker displays these fields beneath the Description field. The maintenance request version of the Enter Report Details form, for example, has three custom fields to
Issue 34, February 2015
Southern Communicator
Bug trackers are not just for bugs 21 record the purpose of the maintenance and the safety and environmental risk levels.
Further down the page is a place for notes. The Notes field is where the Problem Solver, for example, reports progress; the Reporter can clarify the request; or a Stakeholder can make a comment.
For problem solving issues, there are different custom fields: The user can read down the page through all the existing notes to see a discussion history of the issue and use the Add Note button to add a new Note. The View Issue History page also contains the complete history of the issue:
MantisBT has a special management area for creating custom fields. You can create fields of various data types and include validation rules. The custom field definitions are global to your MantisBT installation and you can apply them to whichever projects you want. You can add them to the Enter Report Details form or any of the Change Status forms if you require the user to enter these details on change of status.
View issue page The view issue page shows all details about an issue.
Change status pages When it’s time to resolve or close an issue, the Problem Solver or Reporter uses the corresponding change status page. The following example has had two custom fields added to it for corrective action issues.
Southern Communicator
Issue 34, February 2015
22 Bug trackers are not just for bugs
View issues page You can view lists of issues and refine the list using filters and search.
Issue statistics
Email notifications
You can view issue statistics to measure how well people are responding to issues.
Issue trackers can automatically:
Issue 34, February 2015
send email notifications of events receive new issue reports by email.
Southern Communicator
Bug trackers are not just for bugs 23
Project examples A major MantisBT client has 14 different projects that include service, problem solving and record-keeping. To date, over 17,000 issues have passed through their system.
Setting up an issue tracker Installing MantisBT is easy to install, but the installer does need to know how to install files on a web server and set up and connect to an SQL database.
Choose Settings Out of the box, MantisBT is set up for a software development team. The configuration you need for business use is much simpler. Here are some of the settings I would recommend.
Roles and user levels People may take different roles in different projects. In the issue tracker each user has a user level.
Role − the part a person plays in processing a business issue. (Reporter, Problem Solver …) User level − the ‘highest’ role that an issue tracker user may take.
User levels used in business MantisBT comes with six user levels. For business use you only need three or four.
Introducing an issue tracker to a business or project People need some time and encouragement to get used to the idea of using an issue tracker for their assigned tasks. Unless you introduce it properly, people are likely to sidestep and sideline it. I suggest the following steps:
1. Get firm executive sponsorship for introducing it. 2. Introduce one project or purpose at a time.
3. Give thorough introduction and training. 4. Train Reporters to:
Reopen incompletely resolved issues.
Have the courtesy to review and close resolved issues. (This may not be needed for busy internal ordering projects where review of the resolution is not really needed; you can set the issues in projects to automatically close when resolved.)
5. Give moral support to Problem Solvers who refuse requests that are not made through the issue tracker. 6. Show issue listings at meetings and discuss them. Discuss statistics for:
Unresolved issues
Resolved issues not reviewed and closed.
Southern Communicator
Reporter − Can only report issues. This is only needed if team members with a low level of responsibility or customers have access. Note that here we are talking about user levels, not roles. If someone is at the Reporter user level, they can only report issues, not be a Problem Solver. Problem Solver − Normally, most people are at the Problem Solver level. These users can also take the Reporter role as needed. We renamed the original MantisBT's Developer level as Problem Solver. Manager − Has more permissions to change and move issues. The Manager role is responsible for the smooth running of a project. Manager level users can also take the Problem Solver and Reporter roles. Administrator − Manages users and keeps the whole system running. Administrators can take any role.
Stakeholder is not a user level. It just means any user who is interested in an issue. Stakeholders can monitor issues and MantisBT sends them email notifications when something happens in the issue.
Issue statuses Initially, MantisBT has seven issue statuses. For business use, you can reduce it to four: Assigned, Resolved, Closed and Reopened. Initially we started with New (unassigned) as well, but switched to having a default assignee for all issues. The ambiguous Feedback status could be changed to Reopened.
Issue 34, February 2015
24 Head‐up Displays for Technical Communication Custom fields As previously described, you can create your own custom fields in MantisBT. Several have been already been mentioned in this article.
Configuring an issue tracker There are three overlapping ways to configure MantisBT:
Urgency and Severity MantisBT includes Urgency and Severity fields. Disable them unless the user has agreed and there are documented definitions for each Urgency and Severity level. Without this change every issue quickly ends up being an Extremely Urgent Disaster.
Tags MantisBT has a tag (keyword) system. You can tag issues with keywords and then filter issues with those keywords. Once again, disable them unless there is a system, a discipline and a good reason to use them.
Through a PHP configuration file. Once you learn to use it, it is the quickest method. However, I have not yet found a way to use it for individual project settings. Entering the PHP variables and values in the Manage Configurations area. You can create settings that apply to individual projects and users. Using the settings in the configuration pages in the Manage Configurations area. These cover most configuration needs, can apply to individual projects and don’t require knowledge of PHP. To change wording in the user interface, for example the names of statuses, you need to edit the configuration files.
More information In this short article I have only given you a taste of what an issue tracker is like to use in a business or project. Feel free to contact me for more details at
[email protected]
Head‐up Displays for Technical Communication Tony Self challenges us to look to a potential future for technical communication. Think about bi-focal lenses for a minute. You know, the glasses with two lenses: one at the top and one at the bottom. The bottom one is for reading, because you look down when you read, don't you? Because a book is on a desk, or on your lap, or on a table, or in your hands. What about if things were different... if the text you want to read was displayed in ‘thin air’ on the wall at the back of the room? Or on the sky? Now think about the movie Top Gun. (Some of you might be too young to have seen this when it first came out, but it was released at least three Tom Cruise marriages ago. I'm sure most people have seen it, or the parody starring Charlie Sheen. But I digress...) In Top Gun, you may remember seeing gun-sights and cross-hairs and warning messages and airspeeds displayed as green text on the cockpit windshield of the Grumman F-14 Tomcat. That was an early ‘Headup Display (HUD)’. By now, they are far more sophisticated. Some cars now have ‘HUDs’ installed as standard, displaying speed, distance, and messages onto the windscreen, focused on the horizon. You don't need to move your head down to read; you can keep your head up. If you have a smart phone and a dirty windscreen, you can even download a ‘HUD’ app, place the phone on your dashboard, and reflect an inverted speedo readout onto the windscreen.
But there's another type of ‘HUD’ that's attracting the buzz at the moment: Google Glass. Glass isn't the only product of its type on the market (there are dozens), but it attracts the most publicity. These ‘wearable technology’ products display text in a tiny HUD in a pair of lens-less spectacles. The text displayed depends on the application; it could be the time, next appointment, alerts... but it could be procedural information, or checklists, or product descriptions. When coupled with a camera able to identify objects that you see, this technology can enable innovative new ways to deliver technical information. Virgin Atlantic are currently trialing Google Glass with their business lounge staff at Heathrow Airport so that important information is always in front of their staff, whether their heads are down or up. HUDs may have implications for technical communication. Obviously, documenting HUD devices and applications is one area (there is even a police motorcycle helmet where the whole visor is a HUD). It’s hard to predict, but perhaps documentation could be displayed on a HUD? Checklists and other procedural information would seem good candidates. Technical writing techniques such as minimalism and separation of content and form will help make it possible for us to deliver to this new form; to a layer above reality. This article was originally published in the IconLogic I Came, I Saw, I Learned blog and newsletter in April 2014.
Issue 34, February 2015
Southern Communicator
98%
reduction in production time
80%
80%
reduction in turnaround time
70%
reduction in printing and paper material cost
60%
accelerated localization time
20%
reduction in development time for course content
boost in staff efficiency in editing manuals
Real Results. Realized! 600,000+ users across 20,000+ companies worldwide trust Adobe FrameMaker to deliver measurable gains! Upgrade to the power-packed Adobe FrameMaker 12 Now available at a monthly subscription of A$29.99/US$29.99
Call 1800 614 863 (Monday-Friday, 9am-5pm)
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. © 2015 Adobe Systems Incorporated. All rights reserved.
Save more with Adobe FrameMaker 12! Find out how much you can save by using FrameMaker v/s using Word
v/s using other XML editors
Calculate savings
Calculate ROI
Adobe, the Adobe logo, and FrameMaker are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. © 2015 Adobe Systems Incorporated. All rights reserved.
