MadWorld 2016 Conference Review – Day Two

Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. Here is a summary of what I saw and heard on the second day. These were mostly for advanced users; I didn’t see any of the presentations aimed at new users of Flare.

Continue reading

MadWorld 2016 Conference Review – Day One

Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. It’s the most rewarding and enjoyable of all the conferences on technical communication that I attend. Here is a summary of what I saw and heard on the first day.

Continue reading

Presentation on technical writing in Lean and Agile environments

Cherryleaf’s co-founder, Ellis Pratt, will be speaking at the next meeting of the ISTC’s Southern Area Group. The event will be on Tuesday 17th May at The Keep, 29 Castle Street, Guildford, GU1 3UW from 7pm. Ellis will speak on Technical Writing in Lean and Agile environments. He’ll explain how to rise to the challenge of writing user documentation in an Agile environment and how Lean and Agile could be used to manage writing projects.

Doors open at 7pm, and Ellis’s talk will start around 7.30pm. Afterwards there will be the usual opportunity for questions, for serious discussion, or light-hearted chat, depending on your mood and inclination.

The event is free, and open to all, so tell your friends and colleagues! But if you are planning to come, please register on Eventbrite here: https://www.eventbrite.co.uk/e/technical-writing-in-lean-and-agile-environments-tickets-22468971298 and they can let the venue know how much space to reserve for us and how many people are likely to want to order food.

Parking is available in the Tunsgate Multi Storey right next door to the Keep, or the Sydenham Road Multi Storey about 250 yards away, but be aware that some roads in the area are one-way streets, so check your directions carefully.

Reflections on last week’s mini-conference on documenting APIs

Last Friday, I attended and presented at the Write The Docs mini-conference on documenting APIs, held at the Government Digital Services (GDS) building in Holborn. My presentation was called “What makes Technical Communicators uneasy about API documentation, and what can we do about it?”, and there were a number of questions and comments regarding some of the slides that I felt I should expand on.

1. Are there really so few people with API documentation experience?

I showed the results from searching on LinkedIn for Technical Authors in the UK who have API in their profile, to give a rough indication of the number of people with API documentation writing skills and experience. It’s hard to provide accurate figures because:

  • People writing API documentation are not always called Technical Authors.
  • There’s no Standard Industrial Classification (SIC) code in the UK for Technical Authors, which means there aren’t any official statistics.
  • There are approximately 30 million working people in the UK, and only 19 million of them are on LinkedIn.

However, even if we double the number found in the search results, it’s still a very small pool of suitably qualified people.

2. The difference in the skills required for Technical Authors and API Documentation writers.

A lot of people photographed the slide describing the differences in skills required. In the presentation, I pointed out that the priority of the skills could change, depending on circumstances. It’s not in a fixed order.

The main difference is that API documentation requires a much higher level of knowledge about the subject matter. To create an end user guide for an accountancy package, where you are describing mostly tasks, you don’t necessarily need to know a great deal about accountancy. To create an API guide, where you are describing mostly facts, you need to have a greater understanding of the subject matter.

3. The differences in the readers.

I said that Technical Authors tend to describe technical information to a non-technical audience, whereas API documentation writers tend to describe technical information to a technical audience. Some people challenged this statement. I should have said that Technical Authors tend to describe technical information to a non-technical and a technical audience. I believe it’s true to say that the readers of API documentation are more competent technically, and so there will less explanation of basic concepts in API guides.

The event was excellent, with many very interesting speakers. The GDS is working on developing a design pattern for Gov.uk APIs – for example, for the Local Waste Service Standards Project and for the Companies House API. It’s clearly early days for the GDS, but I suspect, where Gov.uk leads, others will follow.

Do you need DITA?

Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.

Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):

“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not  able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”

This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:

You probably don’t need DITA if:

  • The way the content looks to the user is the most important issue.
  • You have fewer than four writers.
  • You write narrative content.
  • You have limited budgets for tools, training and migration.
  • You don’t have the time to deal with the issues around changing working methods.
  • Your content has a “shelf life” of less than two years.
  • You use a lot of graphics with annotations.
  • You need to customise outputs [added] for individual documents [added] (such as PDFs).
  • The cost of migrating existing content will be expensive.
  • You want the presentation layer embedded with the content layer.
  • You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
  • You need to put JavaScript code directly inside topics.
  • You need to use the tools used by developers or the marketing department.
  • You want a simple information architecture.

You might need DITA if:

  • You need to write to (and enforce) a standard.
  • You need to localise content into many languages.
  • You have more than four writers.
  • You want to write semantically.
  • You need a more efficient authoring, [added] reviewing [added] and publishing process.
  • You create many variations of the same document.
  • You want intelligent content that can adapt to different users and contexts.
  • You are spending too much time on formatting content.
  • You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
  • You need to establish a controlled vocabulary and taxonomy.
  • You want content validated for consistency.
  • You want automated publishing.

You probably do need DITA if:

  • You need to share content with other organisations.
  • Your content will need to last more than 30 years.
  • You want content to be stored in an open data standard, independent of any tool.
  • You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
  • You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
  • You want to have a way of generalising back to a common standard.

 

Do you agree?

Please share your thoughts below.

Reflections on the TCUK15 conference

I was one of the presenters at last week’s Technical Communication UK 2015 (TCUK) conference. TCUK is the Institute of Scientific and Technical Communicators’ (ISTC’s) annual conference for everyone involved in writing, editing, illustrating, delivering and publishing technical information. It’s an opportunity for Technical Communicators from the UK and mainland Europe to meet up and mingle, learn and present.

auditorium at tcuk 15 conference

Here are my reflections on the event.

Continue reading