Author Archives: Sarah Maddox

Broadening the definition of technical communicator at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

Kylie Weaver‘s presentation was “Broadening the definition of the technical communicator”. Humans are very good at categorising things. This is very useful, both in life and in the workplace.

Rigid categories can be limiting. Kylie believes strongly that there’s a hybrid role in the workplace: tech writers and business analysts merged together. Technical writers often work through the entire project cycle, from the beginning of development to the end where the product is shipped.

Kylie has observed that poor documentation can slow a project down and reduce its quality. Poor communication leads to misunderstandings. We need more technical writers.

Being involved throughout  software development lifecycle

Documentation is needed throughout the software development lifecycle. The roles involved include technical writer, instructional designer, change manager, business analyst, and project management. Kylie has worked in environments where these roles blur together. Technical writers tend to span all these roles during the course of a project.

Kylie walked through the documents produced at various stages of the SDLC: requirements analysis, specifications, design documents, test cases, requirements for usability testing, user documentation, training material, corporate communications, handover for production readiness, and more. The role of technical writer is traditionally confined to just the user docs and perhaps the training material. We can in fact contribute at all stages. It’s very exciting to get involved right from the start, and we have the skills to do that.

The hybrid role that can span the project is “business analyst/technical writer”. If you are are interested in solving the business problems and talking to the end users, this role is for you.

The importance of (all types of) documentation

Finding out what people want, and documenting that clearly, is essential at the start of the product. Specifications help developers and testers write code quickly and effectively. Kylie walked through the other documentation types, showing how each is essential to the successful conclusion of a project. Technical writers all know about audience analysis. So many business analysts and project managers don’t.

Comparing the roles of technical writer and business analyst

Technical writers translate geek speak into normal speak. And business analysts do it the other way round! We’re all good at creating technical documentation. We all focus on helping people do their job. And we care about the end user. We have good negotiation skills.

We’re all the hub of all knowledge, acting as the liaison point between the big-picture people (PMs) and the details people (developers). Kylie says that this is a particularly difficult aspect of the role. And we find pragmatic solutions.

So, what are the differences? Tech writers focus on the documentation solution, while BAs focus on the technical/software solution. TWs may focus on a specific procedure, whereas BAs often have a broad focus on business process. And both groups focus on different documentation standards and conventions, as defined for their roles.

BAs facilitate workshops, so this is something a TW may need to learn. They also manage the expectations of users’ and subject matter experts’.

How to move towards this hybrid role, if you want to

Look for opportunities and offer to help. Remember how you became a technical writer – you probably merged into it in much the same way. Remember that you have extremely valuable skills. It’s a joy to read a document written by a technical communicator.

Step back and look at the big picture.

Look back at the roles you’ve already filled. You’ve probably done part of the BA role already. Kylie gave some examples of hybrid-role projects she had worked on. One was an IT architecture project, connecting front end and back end systems. Kylie came into the project when it had been going a while, and was asked to define the scope of the end-user training that would be required. She found that none of the design or solution had been decided or documented yet. So she let the team know that they needed to define the business processes, and helped do that. She and the team created templates and a SharePoint site, pinned something down, and brought success out of the ashes. If they’d had a BA at the start, the project would never have been at that state by the time Kylie was called in.

Is this role for you?

An awesome, fun-filled section of the talk was Kylie’s overview of her motivation for “stepping between worlds”. She told us what she enjoys, and how it fits into the hybrid role of BA/tech writer. Basically, it’s just “tremendously exciting” and it all comes down to this: “if you enjoy getting your breakfast routine down to the most efficient sequence of tasks, then this role is for you.” :)

Conclusion

This was an inspiring, humorous, and buoying talk. Thank you Kylie for a unique, personal, authoritative session. Kylie’s favourite project was documenting how to refuel aircraft at Mascot airport!

Issue trackers at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

David Stephensen presented a session titled, “Issue trackers are not just for complaints and bugs”. The presentation covers the basic operation of issue trackers, uses of issue trackers and how to set them up for use in business, and ideas for the use of issue trackers in your work. This third aspect, David says, will hopefully be in our imagination as he talks.

Basic operation of issue trackers

An issue is a request for action – someone asking someone else to do something. David talked about 3 basic statuses: assigned, resolved, closed, plus the possibility of another status: reopened.

The roles define the players in the issue, including the reporter (person who raised the issue) and problem solver (the person who did the work). Another potential role is manager.

An issue tracker manages issues through the cycle of statuses. There are a number of issue trackers out there. David chose Mantis Bug Tracker, which is free and is known for being simple. It allows basic configuration, enough to make it useful in business.

What do you need of a bug tracker in business?

Recommended features in an issue tracker:

  • Customisable workflow
  • Custom fields
  • Multiple projects
  • Full text search

Plus desirable features:

  • A plugin API
  • Support for Unicode

Record keeping is paramount. You need an audit trail for meeting minutes, audit reports, and to act as a statement that an action was taken.

The case study

David walked us through the procedure of creating an issue for one of the projects he’s worked on.

First, a list of existing issues shows the status of each issue, colour-coded by status. The list also shows the issue ID, due date, category, reporter, and more fields. To report (create) an issue, there’s a generic form. You fill it in and hit submit. An issue is logged in the system and the assigned person receives an email.

Issue types may include:

  • Request for service – please do something for me. Examples are maintenance requests and purchase requisitions.
  • Problem report – please fix it.
  • Something to record

For each issue type, it’s possible to add custom fields. That is, fields that are applicable to a particular type of issue. For example, for a maintenance request you may add a field to indicate severity, and another to indicate whether the problem has caused an injury or not. We saw an example of a maintenance request, noting that the lighting in a particular area (bay 6) needed fixing.

Another type of issue is a problem to be solved. There are 4 stages in a Corrective Action, and David showed us how he had included these stages in the issue tracker:

  • Containing the problem
  • Correcting the problem
  • Finding the root cause
  • Removing the root cause

The example was a person requesting that someone investigate the way an item was connecting with another. This was a preventive action, to ensure something doesn’t go wrong.

David demonstrated the third type of issue: something to record. This isn’t really an issue, but hi-jacking the issue tracker to ensure that you have a record of something, such as meeting minutes, audit reports, or a statement that action has been taken. The example was someone asking someone else to sign off on a review. Issue trackers have an indelible date stamp, which is very useful.

Following through on the lifecycle of an issue: People can add notes. It’s important for the problem solvers to report their progress, so that the report can see the updates. When the problem is fixed, you should resolve the issue on the tracker.

It’s possible to group issues into a project, which is useful for organising your issues. Being able to find issues is very important too, especially when there are 16000 issues on the tracker, as there were in the case studies. We looked at the filtering capabilities of the Mantis tracker, used to tailor search results. We also saw an example of the email notifications that the issue tracker sends when an event occurs, such as then an issue is assigned to you. You can also add yourself as a monitor of an issue, when you’re interested in receiving notifications about the progress on that issue.

A beautiful thing about issues is that everything that happens is recorded, and is visible in the issue history. David shows us an example, included the fact that files had been uploaded to the issue, it has been assigned, etc. The issue tracker display statistics, such as number of issues opened, resolved, or closed, and so on.

Getting a team to adopt an issue tracker

This can be tough. You need:

  • Strong executive sponsorship
  • Gradual introduction
  • Training

Tip: Acquire some allies. Get people to reject things if they haven’t been reported properly. Ask problem solvers to refuse requests unless they’re in the issue tracker. Show and discuss the statistics during meetings.

Simplifying an issue tracker for use in business

David showed us some techniques for reducing the number of roles and statuses, and other features of the tracker. For business use, you don’t need all the features that are useful in software development. We ran out of time a bit here, so we had to go through the configuration rather fast.

Conclusion

It was interesting to see Mantis at work, and to see the case study of how an issue tracker was used in a specific environment. Thanks David for an excellent introduction to configuring and using an issue tracker.

Increasing your visibility at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

Adrienne Mclean presented a session titled, “Increase your visibility – 6 ways to promote yourself”. The session looks at marketing: ideas and ways to promote yourself, that you can use in the workplace and as a small business owner.

There are more than 2 million small businesses in Australia. How do you make yourself stand out? Here’s an overview of the presentation:

  • Why businesses need to innovate
  • Marketing principles
  • 6 marketing approaches
  • How to stay connected with your audience
  • The 4 step process for implementation

The presentation was primarily targeted at small business owners, but Adrienne emphasised at the start that these techniques are applicable in the workplace too.

Innovation

Adrienne talked about some businesses that have shown innovation. McDonalds diversified from the plain hamburger. IBM from hardware to software. Apple is know for its innovation, says Adrienne. Innovation is important in marketing, as well as products and services.

Marketing principles

Think about these questions:

  • Who do you serve? Who is the target customer? Adrienne uses a marketing system called Book yourself Solid.
  • What do you help your customers do? You need to be clear about this, so that you can fine tune your offerings.
  • What do you stand for, and what makes your business so important?

Define your message. People want to know who you serve, what you stand for and what you will help them do. This is what people are looking for when they come to your website. The clearer and more concise your message is, the more likely your customers are to interact with you.

Be yourself, so that you can be passionate about what you do and so that you can let your clients know this.

6 marketing strategies

What we’ve already looked at forms the foundation. Now the 6 core strategies come into play.

  • Networking is the core of any business. It’s mandatory, says Adrienne. Use a CRM system, such as Contractually (which Adrienne uses) to keep track of contacts and to share information. Introduce people to each other.
  • Outreach is also mandatory: go out and look for people who may be able to help you. For example, you may be looking for quality assurance coordinators. Find out the names of some people at the Australian Bureau of Standards. Link to them on LinkedIn. Find someone else who knows them, and get them to introduce you. For example, for this presentation Adrienne looked for people who might want to sell their services. She made connections with people who are now interested in seeing the presentation. The lead time may be quite long.Adrienne met someone in April, which resulted in a presentation booking at the end of October.
  • Asking people for referrals is another mandatory activity. Be proactive. Ask the people you know or meet to refer you to someone else. The “gang of five” is a technique where a group of 5 people are associated with each other, although they all do different things. They refer each other for relevant roles.
  • Speaking is not mandatory, but is a wonderful way of getting your business known. It’s one-to-many whereas networking is one-to-one. Think about video as an interesting channel. You’re speaking one-on-one (typically, only one person looks at the video at a time) but it’s one-to-many in that it reaches many people. Embed your videos on your website. They’re a great way for people to get to know you and get a picture of you and your business. It’s a way of building rapport with people. Adrienne talked us through some presentation skills, such as confidence, rehearsing, knowing your audience, and more. Adrienne uses the Speaker’s Training Camp program, which focuses on steak (the content), sizzle (what makes the topic important) and style (the way the presenter presents). This program is similar to ToastMasters, but for presentations. Look at ReelSEO for enormous amounts of information and content around video marketing. Adrienne talked through the benefits of video marketing, including the increase in likelihood of purchase by 1.8%, and a more than 50% increase in views of press releases.
  • Writing is particularly applicable to technical writers. Write articles relevant to our world of technical writing. Perhaps specific “how to” tips on tech writing, or wider topics such as writing for business, how to prepare eBooks, the process of putting a novel together, writing for small business.
  • The Web – use it to post videos and articles. Find the social media platforms that work for you: Twitter, Facebook, LinkedIn, blogs and so on. Choose one or two social media platforms that work for you, and post regularly there. Adrienne compared LinkedIn to the yellow pages. She posted an update on LinkedIn and got 1100 views. This would not happen in the Yellow Pages, she says. Also, the social media are international.

Staying connected

Find ways to stay connected with the people you serve. Social media, mentioned above, are very useful here. You’ll see what people are doing in your world. Writing is a way of building your credibility, and you can post it on social media to show yourself as an expert in your field.

Write newsletters. Use an email marketing system like Mail Chimp. Produce promotional videos and how to tips and put them on YouTube – it’s the second-largest search engine now. Produce webinars or Google Hangouts. The hangout can be videod, which you can then edit and publish on YouTube. You can screenshare on Google+. Write articles and put them into eBooks. Books are the best business card. Self publishing is a valuable technique in marketing. Most professional speakers have a book and vidoes.

Implementation in 4 steps

We ran out of time, so Adrienne just mentioned these 4 steps:

  • Planning
  • Practice
  • Presentation
  • Promotion

Conclusion

Thanks Adrienne for a gentle and persuasive introduction to marketing yourself.

Embedded help at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

This is Dave Gash‘s second session at the conference! It’s called “Embedded help: nuts and bolts”. The aim was to show us how to do embedded help, rather than why embedded help is a good thing. Dave said there’ve been plenty of presentations in years gone by, explaining when embedded help is required and what it looks like.

The goals is to show us two ways to add embedded help to your web app:

  • Put the snippets into an HTML help page
  • Put the snippets into an XML file

Dave explained that his code samples are plain old JavaScript rather than using a library like jQuery, because it’s more accessible to everyone and because it will work locally.

First method: Adding embedded help via HTML

For the purposes of this demo, Dave has created a “phony” web app: GalaxyDVR (HTML). Notes:

  • Look at the embedded help panel at the bottom.
  • remember Dave’s warning that the aim is to show us how to create embedded help, not how to make it beautiful.
  • See how the content of the bottom panel changes when you click on different parts of the screen.
  • Click the link in the panel to see the full help system.
  • Note how the first sentences in each section of the full help system correspond to what appears in the panel on the app.

Dave said that this is the more difficult than using DITA, but still very feasible. It works by using a CSS class of “shortdesc”. The web app reads the entire content page and looks for the paragraph that has the class of “shortdesc” and sticks it into the <div> that defines the help panel.

How to prepare the content: Create it with any tool that allows you to define a specific reachable HTML element. It doesn’t have to be a CSS style. It could be a <span> with an id, for example. You could even style it so that it doesn’t appear in the full help system.

Dave was using DITA for content storage, which was then transformed to HTML that contained the necessary identifiers. But he emphasised that you don’t need to use DITA. You can have straight HTML instead.

The help files must be accessible to the web app.

How to retrieve the help content when the user clicks the relevant area of the page: A JavaScript function reads the entire HTML file as a string, finds the content identified as embedded help, extracts it to another string, and embeds it into the panel.

Now Dave walked us through the code that does the work. I haven’t tried to capture this in the notes. Some extra bits to note: The page loads some default help content via the HTML body’s onload event. Another piece of code tacked on the standard string that says “For more information, see the full help system“. And remember to add CSS to style the embedded help content.

Second method: Adding embedded help via XML

See the demo app: GalaxyDVR (XML). This one is based on XML. Note also that there’s a specific piece of embedded help for each control on the page, rather than for just the sections. There’s also help for each element of a dropdown.

Dave says this version is much simpler. You don’t need a web help system. Create the embedded help all in one file. You can use any XML text editor. The XML can be of a format of your own choice. The input and output is just a file. There’s no build or conversion process required.

Every embedded help snippet has an id, which is a unique identifier. You can use any naming convention you like. For example:

<eh id="fc_avail">My help text</eh>
<eh id="pc_pin">More help text</eh>

When the user selects a control, the JavaScript looks in the XML file, locates a specific piece of text that matches the control, and returns the help text into the box on the screen. How does it identify the relevant text? The element that the user clicks has an id that matches the id of the help text element. The XML file is read into an XML document object (rather than as a string). Then you identify the help text, extract it, and embed it into the help panel.

Note: Instead of using the onclick event to trap the user’s action, you’ll need to use onblur. Otherwise you’re overriding the core app functionality by usurping the onclick event. Also, people may want help before they actually click the button. Using onfocus will work when users tab through the fields too.

Comparing the two methods

Dave emphasised that neither method is better. Think about what you want to do:

  • The HTML method creates the entire web help system including the embedded help content. That’s single sourcing. Also, the HTML method less granular, and distributes the embedded help content amongst the other content. You need an entire separate help system, including some kind of build system to create the web help system.
  • The XML method is not single sourced. You may end up with a set of embedded help content and a separate set of web help content. But this may not really hurt you. You just need to ensure you maintain both. The XML method is more granular, and it keeps all the embedded help content together. You’re not required to have an entire web help system.

Dave also noted that his implementation is just an example. Take his code and change it to suit your requirements. The goals of Dave’s presentation are to show what’s possible and help us feel we can do it.

Conclusion

This was an excellent walkthrough of a couple of embedded help solutions. Thanks Dave for a couple of great demos!

Videos and screencasts in technical communication at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

Charles Cave presented a session titled, “Don’t tell me – show me!” It’s about videos and how they can be used in technical communication. We all know that in real life, if you can get an expert to show you, that’s the best way to find out how to do something. Note that a video can be very short, even 20 seconds. It doesn’t have to be long, to be effective.

Charles told us a story of how he needed to solve a plumbing problem at home. He looked around for instructions, but didn’t find any. Then he looked on YouTube, and found 2 videos. One was very short and simple, illustrating how to replace a filter in a toilet cistern. The other was longer, and presented a large amount of technical information effectively. This works well for something as simple and tactile as plumbing.

In technical communication, we can use a screencast with some sort of narration to show someone interacting with a computer. Charles told a story of how he tried to explain to a friend how to use a website:the Stanton Library website. He started explaining, but decided this wasn’t an effective method.

Our options for showing someone how to do something:

  • A textual description of the steps
  • Screenshots with annotations and callouts
  • Video with voice-over
  • Video with voice-over and callouts

Here Charles played a video he had created, showing the steps you need to take to search the library for new items on the Stanton Library website. This was a straight recording using Camtasia. He usually does a voice-over, using Audacity (open source and free of charge) to edit the audio track. You can remove background noise and do other editing to achieve a reasonably high quality. Before doing the recording, Charles creates a script and makes sure he has all the software ready to go.

With Camtasia, you can add callouts. Charles demonstrated callouts using arrows overlaid on top of the video, shape drawing, and spotlights which make part of the screen dark so that our eyes are directed to the important part of the screen. There’s a lot  you can do in Camtasia, with zooming and panning and more.

Captions or subtitles are useful on videos, particularly for those situations where people can’t listen to the sound. For example, if they’re in a noisy place or with other people. Charles used the captions to point out the important steps in the procedure.

Let’s assume you do need screenshots as well as the video. With Camtasia, you can export the current frame as a PNG file. When using screenshots, it’s sometimes difficult to see what’s changed on each screen. And it takes time to write the words that accompany the screenshots. Charles says that producing the video can be quicker, and also more friendly to the user. Adding a friendly narrator adds to the friendliness.

To consider when considering creating a video as opposed to textual instructions:

  • How effective are the instructions?
  • How much time and effort will it take to produce the video?
  • Is the video usable without sound?
  • Where will the video be watched – PC, Android, iPhone, etc?

What about video format? Charles recommends MP4 as the most universally useful format.

Charles touched on live-action video, such as filming with a smart phone. Nowadays our smart phones have high definition cameras and are useful tools for creating videos. You can get some useful accessories for the phone, such as a tripod. Also consider light defusers, and setting up a little home studio.

With Fuse from Techsmith, you can transfer videos directly from the phone into Camtasia over a WiFi connection.

You can make videos from still images. Charles uses PowerPoint, and saves each title slide as a PNG file, then includes those into his video. Charles showed us a couple of attractive title slides he’d made. You can also take a number of very clear photos of hardware, for example, and use those in a video flow instead of a filmed video.

You can make screencasts from a mobile phone using Reflector from Squirrels. It runs over the WiFi network. When you’ve connected your iPhone, everything on the phone appears on the screen e.g. your Windows computer. Then you can record it using Camtasia.

What you need to product a video:

  • The producer/director: you
  • The script: a plan or list of steps
  • The camera: Camtasia or a smart phone
  • The sound recording: a microphone and Audacity
  • The voice: Charles says doing this yourself is a very good option. Getting someone else to be the talent is also an option, but they’ll need training.
  • Actors, if you need more than one person: You, and perhaps some colleagues
  • The audience!

Conclusion

Thanks Charles for a great introduction to using videos in technical communication. Charles has put more information in his blog post: Don’t tell me – show me!

Follow

Get every new post delivered to your Inbox.

Join 1,508 other followers

%d bloggers like this: