Author Archives: Sarah Maddox

The DITA debate

I’m coming to the conclusion that there are specific types of content that suit a DITA environment, and that the converse is also true: DITA is not the best solution for every content type. (DITA is the Darwin Information Typing Architecture, an XML architecture for designing, writing, managing, and publishing information.)

“Well, duh,” you may say. :) I’ve never worked in a DITA environment, but I’ve attended two indepth training courses and a number of case studies that walked through successful DITA implementations. The most recent was at the ASTC (NSW) conference last week, where Gareth Oakes presented a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website. (See my report on the session: Repco and DITA.) This was a convincing case study of a situation where DITA has succeeded very well.

In my analysis, the DITA implementations that work well are those where the content consists of a large number of topics, and where those topics have an identical structure. It’s almost as if you’re building a database of content. Good examples are catalogues of automotive spare parts, machine repair instructions,​ safety procedures, aircraft manufacturing manuals, and so on.

Apart from volume and support for a standard layout, this type of content has other requirements that DITA can satisfy well, including the ability to automatically build a variety of manuals by combining the topics into different configurations (via DITA maps) and multi-channel publishing.

On the other hand, some content doesn’t benefit much from such a highly structured storage format. Potentially, the overhead of a DITA environment is overkill and the costs may outweigh the benefits. If we have contributors to the docs who are not tech writers or developers, asking them to learn DITA or specific source control and editor rules can be a deterrent.

Dare I say it: Much of the documentation we write in the software industry falls into the latter category. Our topics tend to be lengthy, less uniform in structure, and more discursive than, say, an auto parts manual. API reference docs are an exception, but they’re auto-generated from software code anyway. We also don’t usually need to recombine the topics into different output configurations, such as different models of a car.

What do you think? Please contradict me. :) Do you have examples that gainsay or support the above conclusions? I’d love to see some examples of well-structured and well-presented documentation produced from DITA source.

ASTC (NSW) conference 2014 wrapup

This week I attended the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. This post is a summary of the conference, with links to individual blog posts on each session, and a thanks to the organisers.

The conference took place over two days, Friday and Saturday, in Sydney. There were 40 to 50 attendants each day. Because one of the days was a weekday and the other a Saturday, a slightly different set of people attended each day. This has been a characteristic of this conference over the years. I think it’s a clever design, giving more people the opportunity to be there for at least one of the days.

Thanks

A huge thank you and kudos to the organisers for putting the conference together. From my point of view as attendee and presenter, it ran without a hitch. (Well, except that the presentation gremlins hopped up and snaffled the internet connectivity during my session. But as a few people pointed out, that’s my fault for attempting a live demo during a presentation. :) ) The sessions were interesting and educational. People were enthusiastic and friendly. Networking was fun and productive.

Thanks to the ASTC (NSW) committee, the presenters, and all the conference delegates. It’s a wrap, and a good ‘un.

The sessions

There were six presentations on Friday and seven on Saturday. I attended all of them, presented one of them, and blogged about almost all of them. The links below point to my posts, in reverse chronological order:

There were two more sessions that I attended but didn’t blog about, because their format didn’t lend itself to live blogging:

  • Responsive HTML5 publishing, by Brian Chau of Adobe. This was an informative session in which Brian showed us statistics of the number of apps developed in HTML5, eBook, and native mobile (iOS and Android) formats. The last is growing strongly. Then he showed us how to use Adobe products to author content and then build it into multiple formats as required by our customers. The primary products he demonstrated were RoboHelp and FrameMaker.
  • Using diagrams to improve your writing (and be happier and live longer) by Daniel Moody. This was an interactive session where Daniel described three types of diagrams that are useful in planning a document before you start writing, and we then practised creating each type. The three types are: associative (but I’ve forgotten the exact term Daniel used), mind mapping, and pyramid.

And the remaining session was my own…

My session on API technical writing

The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that I didn’t include slide 51 in the ASTC session.) It’s a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.

Here’s a summary of the presentation:

  • Introduction to the role of API technical writer.
  • Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
  • What an API is and who uses them.
  • Examples of APIs that are easy to play with: Flickr, Google Maps JavaScript API
  • Types of API (including Web APIs like REST or SOAP, and library-based APIs like JavaScript or Java classes).
  • A day in the life of an API technical writer—what we do, in detail.
  • Examples of good and popular API documentation.
  • The components of API documentation.
  • Useful tools.
  • How to become an API tech writer—tips on getting started.

Playing with a REST API: During the session, I attempted a live demo of the Flickr API. The internet connection went missing, so I had to just talk us through it rather than show it. If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.

Playing with a JavaScript API: My second demo showed an interactive Google map, embedded into a web page with just a few lines of HTML, CSS and JavaScript. I used the Google Maps JavaScript API. If you’d like to try it yourself, follow the getting started guide in Google’s documentation. You’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. That code is what you’ll find on slide 28 in the presentation.

There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!

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.

Follow

Get every new post delivered to your Inbox.

Join 1,495 other followers

%d bloggers like this: