Conference on Agile documentation

The Gov.uk GDS team is organising a one day, free of charge conference in December, where speakers will discuss techniques for writing documentation in an Agile environment, and how to make your content Agile:

  • Tips to writing continuous documentation, ensuring it stays up to date.
  • Tips to getting the development team to value documentation.
  • Knowledge of the tools available to help you write Agile docs.
  • Understanding of how much documentation to write and when to start writing it.
  • Suggestions of how writers can become part of the product development cycle.
  • Understanding of how to overcome challenges that come with working in Agile environments (where the focus often tends to be on the product and not on the content).

This free event will be held in Victoria, central London. Cherryleaf’s Ellis Pratt will be speaking at the event.

See:
https://www.meetup.com/Write-The-Docs-London/events/234913157/

Agile the Docs speaker request form

Customers as Advocates Conference 2016

I thought I’d mention a conference I’ll be attending this month – The Customers as Advocates Conference.

“Customers as Advocates” focuses on the challenges of creating successful customer relationships that lead to reference and case study programmes.”

Although it is aimed at professionals that sell and market enterprise technology, I found it very informative, as a great deal of it relates to User Assistance and other forms of technical communication.

I attended this (free) conference last year, and I particularly enjoyed the presentations on developing and nurturing a thriving community of advocates.

“More than 70 percent of the buying journey is complete before a customer looks at your marketing or engages with sales. Who are your prospects and customers speaking to, and what are they sharing about the experience?” Ian Williams, Director, Jericho Consulting

The conference will be held on Thursday 26 May, in London.

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.