Author Archives: Sarah Maddox

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar.:)

tcworld India 2016 wrapup

This week I attended tcworld India 2016 in Bangalore. It’s been an amazing, rewarding experience. Here are some of my impressions, and a roundup of the posts I’ve written about the sessions I attended.

Tcworld India is an annual conference run by TWIN (Technical Writers of India) and tekom Deutschland. This is a great event, attended by 350 energetic, knowledgable technical communicators.

In his introductory speech at the start of the conference, Akash Dubey said that the great thing about tcworld India is the learning that happens in the corridors. That is so true! At every step, I met people with things to discuss, things to show, questions to ask, answers to propose.

The stage before the start of the conference, awaiting words of tech comm wisdom:

tcworld India 2016

The sessions

There were 8 time slots on each of the two days of the conference, with up to 4 sessions running in each time slot. In total that makes approximately 30 sessions, covering topics across a range of areas: content strategy, tools, technologies, trends, usability, authoring and editing, structured writing, career development, leadership, localisation and translation, and more.

The following posts contain my notes about the sessions I attended:

Bangalore

The conference took place in Bangalore, India. My travelling bookmark has some impressions of the city to share: Bangalore peace and traffic.

Thanks

Thank you to the organisers of tcworld India 2016, for a very well planned event and a skilfully constructed program. The care that you put into this conference is obvious. Walking around the halls, I saw happy, busy, engaged attendees and packed sessions throughout.

The party!

Technical communicators in Bangalore sure do know how to throw a good party. The venue was beautifully decorated:

tcworld India 2016

We started with a few song and dance numbers from some very talented technical writers. I filmed some short videos, which capture the spirit and beauty of the event:

Another dancing item:

There was so much more. Guitars:

tcworld India 2016

A sax:

tcworld India 2016

Singers:

tcworld India 2016

A huge thank you to the performers who put so much effort and talent into the show. I was blown away by the beauty of it, and so were all the attendees. Talented technical writers indeed!

After the show, the rest of the crowd got into the dancing scene:

tcworld India 2016

Thanks again, tcworld India 2016!

API Technical Writing – tcworld India 2016

This week I attended tcworld India 2016 in Bangalore. What an amazing experience! I’ll write a summary of the conference soon. First, here are some notes on a session that I presented at the conference: “Introduction to API Technical Writing”.

The slides for my presentation are available on SlideShare: Introduction to API Technical Writing (slides).

Presentation overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer, and of our audience – the developers who need our documentation to use
  • APIs in their applications.
  • A technical writer’s view of the types of API we might document.
  • Demos of 2 APIs that you can play with yourself.
  • The components of API documentation.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.
  • Why API technical writing is a good field to be in.

API Technical WritingThank you so much to everyone who attended the talk. The room was packed to overflowing. After the session, and indeed throughout the conference, people came up to discuss the field of API technical writing and to show me things they were working on. A number of conference attendees do API documentation as part of their role, and it was very interesting to see the variety of requirements even in this niche within a niche: API documentation within the technical writing profession.

For the next tworld India, I think it’d be a good idea to have a panel discussion on API documentation. We could invite 3 or 4 people working on different types of APIs, and within different environments (such as internal versus external documentation, or integrations).

Are YouTube and Google Making Technical Writing Redundant? tcworld India 2016

I’m attending tcworld India 2016 in Bangalore. The last session of the day was a panel discussion with the enticing title, “Are YouTube and Google Making Technical Writing Redundant?” The moderator was Edwin Skau. These are my notes from the session.

Note: By “Google”, the panel means Google Search.

Edwin started by saying that for the past few years, there have been prophets of doom foretelling the end of our discussion. In the age of YouTube and Google, what is the role of technical communication.

The panelists were Rajesh Chandrasekhar,Nihal, and Parveen Mittal.

Rajesh Chandrasekhar kicked off the discussion. He thinks the answer to the question is, it depends. If you think of the job as someone who publishes, then yes, your job may go away. But if your job is to make sense of the information out there, and to understand users’ problems, then our job will remain. Writers become curators of information. We collaborate on putting the information together – see the world of wikis. It’s a deeper understanding of the customer workflow that enables us to put documentation together. Rajesh showed us a configuration guide compiled from infographics, as a simpler, visual way of absorbing information.

At this point, there was discussion from the floor about the practicality of video guides.

The next panelist was Nihal. For apps, you need a nice way of describing what the app does, said Nihal. He gave 2 examples. A friend of his wanted to connect his phone to Nihal’s car. It was a very complicated procedure, and in the end they couldn’t do it. So they examined the user manual, which was a very thick book. Couldn’t find the information. So then they searched on their phones, and found a YouTube vide that helped them find the answer and do the task within 5 minutes. The video didn’t come from the car company, but from a third party.

Nihal’s second example was a game app that he was playing. He had an issue with adding another player to the game. On the website he found documentation in a question and answer format, and found the answer very easily.

So, in one case, YouTube was the answer, in another it was a technical document.

As a third example, Nihal described a product of his own, which helps people find each other in a certain environment, such as in a conference. He’d explained this app so often, but still the same answer came up: what does the app do. So he created a YouTube video, which does the job well. To create the video, he used a group of creative writers. So no, YouTube does not mean the death of technical writing.

The third panelist was Parveen Mittal. He decided to flip the question, and see what opportunities there are for technical communicators. YouTube and Google are additional channels that we can use. When you need serious information, you need technical writing. He thinks there are massive opportunities, but he’d like to wait for questions before sharing his thoughts.

There was quite a bit of discussion around dating sites at this point, Kinder, eHarmony, and other ways of connecting people. I have to confess I got a bit lost about the relevancy here.

Parveen thinks the amount of work for technical writers will not be reduced. There’ll always be a requirement for some documentation. Edwin made the point that in some cases, there’s a legal requirement for documentation. Regardless of the delivery mechanism for content, someone still needs to design the information.

A member of the audience pointed out that she and many people needed a starter manual, when getting a new product, so that they can confidently start using the product without being afraid of spoiling it or breaking it.

Rajesh pointed out that when you get an iPhone, there’s no manual that comes with it. The expectation is that the design is so good, no documentation is required. A member of the audience pointed out that technical writers are getting involved in the user experience design, that enables such great product design.

Edwin brought curation of user-generated content, and crowd sourcing, into the discussion, asking what the advantage is. Rajesh said the advantage is that you’re making use of the experience of the people out there. Edwin pointed out that there are users who have been using the product for longer than most employees have been with the company that designed the product.

Nihal pointed out that the ability to express the user’s requirements and write clear, useful documentation will always be useful.

A member of the audience said that a study had showed that 75% of the features of a product aren’t used as designed. How do we determine what the customer wants, and how the customer will use the product. Parveen said that crowd-sourced and collaborative technical writing plays a part here. As the UX becomes simpler and the underlying technology becomes more and more complex, you need crowd-sourced answers to issues that arise. Someone else will have had the problem you encounter, and will have solved it.

If technical writers try to stick to writing PDF documents in a dark corner (an analogy that’s been used a few times in the conference) then we’ll become outdated. But if we’re willing to change, there are plenty of opportunities open to us.

A question: Do you think there are limitations to search engines, such as Google, that are preventing users from finding information. Is this so, even though the algorithms are so good, and what can we do to solve the problem? Rajesh suggested running the search engine against your own company’s database, find any shortcomings, and improve the search engine.

Edwin closed by saying that we all agree. Yaayyy. He also suggested that we should consider writing outside our jobs, expanding our skills, and providing information in the places where people are looking for it. So, technical communication is a field that is growing with all these changes, not shrinking.

The consensus was that our profession isn’t going away. Yaayyy.

When Bad Design Happens to Good People – tcworld India 2016

I’m attending tcworld India 2016 in Bangalore. Edwin Skau gave a presentation entitled “When Bad Design Happens to Good People”. These are my notes from the session. All credit goes to Edwin, and any mistakes are my own.

Edwin started by saying that he focuses on how people think about what they do, rather than teaching people how to do something.

He told the story of the Steve Harvey, who mistakenly announced the wrong winner of Miss Universe 2015. Edwin showed us the card that Steve read the winner from, and we discussed how the design of the card led to Steve Harvey’s mistake. The mistake could have been prevented with better design. When bad things happen to good people, good people fail.

We looked at some definitions of design, and settled on this: “Design is a decision or decisions made to achieve a specific purpose.”

The purpose of training is to change behaviour. The purpose of technical communication is to empower users. Bad design leads to failure.

We looked at some hilarious examples of bad designs. An ATM that was high on a wall, and thus out of reach. Funny, frustrating error messages. Edwin had the audience giggling and even roaring with laughter. Then we saw an example of good design: a gadget that helps you put the pleats in a sari.

Jared M Spool talks about 3 approaches to design:

  • Self design – design something to suit the way you would use it. This often fails, because often you’re designing for people who are not like you.
  • Unintentional design – the design is forced by a decision made by someone at some time.
  • Research-based design – this is the best form of design. It’s based on user research: what the user uses the product for, what their win factors are, and so on.

Edwin discussed the features of good design. A well designed product is functional, useful, aesthetically pleasing, intuitive (making a user manual unnecessary), honest, and durable.

What about failures in information design? Edwin gave some examples, from some projects he had seen. These are some of the examples he mentioned:

  • Tabbed pages. Tabs hide information.
  • XML tags for every style.
  • PDF files produced from XML, where all topics of a particular type (concept, task, reference) are sorted together. This results in a guide that fails to help a user with a particular type.
  • Choose a tool first, then build a strategy around it.
  • Content sorted in alphabetical order by title.
  • Document the features, not the usage.
  • Forcing documentation into sprints. This can lead to over-documenting, and documenting what the developers have done rather than what the users will do.

You need to design the documentation process based on what you want to get out of the: where are we now, where are we going, what’s the most efficient way to get there from here. You must also figure out what you should not do.

A closing thought from Edwin: Quick wins are often the enemy of long-term gains.

I loved Edwin’s style of telling stories to illustrate his points. Thanks Edwin!

Follow

Get every new post delivered to your Inbox.

Join 1,695 other followers

%d bloggers like this: