Cherryleaf 2017 European technical communicators survey results – Part 2 UK Salaries

Here are some more findings from our recent survey of European technical communicators. These relate to UK salaries. Most of the people who responded to our survey were based in the UK, so we are able to look at these in more detail than other countries.

UK salaries

We asked people to describe their seniority levels: Junior, Line staff/Standard, Senior/Team Lead, and Manager. These are often a key factor in the salary someone earns.

LevelSalary (Mean)
Junior£32,000
Line staff/Standard£37,826
Senior/Team Lead£50,982
Documentation Manager£49,620

Excluding managers, the mean was £45,338.

Are the figures accurate?

The sample size was fairly small (n=61), so  we do need to look at this information with some caution.

Data on the Technical Author salaries offered on the main IT jobs boards in the six months to August 2017 show a UK median annual salary of £50,000 (with a median of £47,000 for jobs offered outside of London). They also show a 25% increase in median salary offered (17.5% increase for jobs offered outside of London) since August 2016. That’s based on 167 job adverts – again a fairly small population. We also need to bear in mind the salaries in job vacancies can be higher than those for people who have been a job for a long time, and the number of Technical Author job adverts has decreased in the last 24 months.

See also : Cherryleaf’s recruitment service – Technical Authors and other content developer roles

Example project – API documentation portal using MadCap Flare

Note: This post follows on from two previous posts on creating a unified API documentation portal:

We’ve just uploaded an example project of an API documentation portal created using MadCap Flare:

The documentation portal includes API reference documentation that was generated automatically from a Swagger/OpenAPI specification file.

Whenever the REST API specification is updated, that content automatically updates itself in the Flare project.

Using MadCap Flare means you can provide a consistent user experience: for the reference, troubleshooting, getting started and tutorial content. Flare also manage the content, search, linking, pdfs, tables, flowcharts etc.

The steps are:

  1. Generate the API reference documentation in HTML format from the OpenAPI specification file. This could be generated automatically each day.
  2. Import the API reference HTML file into Flare. Select Link Generated Files to Source Files. This creates a connection between the original HTML files and the files that are created as a result of the import. Flare recognises when changes have been made to the source documents.
  3. Fix any initial CSS issues. The API reference HTML file links to a cascading stylesheet file. We found we needed to create a CSS file with the same name, as there were some issues with displaying the top navigation menu bar.
  4. Generate and publish your web site. You can run Flare’s “Build” command from the operating system’s command line. This means you can create a batch file with the necessary commands in it. Then you can use a scheduling tool to run the batch file automatically.

Further work could be done to improve the outputs:

  • We’ve not made any changes to the default styles for the PDF manual.
  • Amending the cascading stylesheet for the Stripe-style API documentation
  • Adding code samples.

See also: Cherryleaf’s API documentation writing services

Book – Current Practices and Trends in Technical and Professional Communication

This week, the Institute of Scientific and Technical Communicators published a book, called Current Practices and Trends in Technical and Professional Communication. Cherryleaf’s Ellis Pratt is one of its co-authors.

book cover - Current Practices and Trends in Technical and Professional Communication

“Technical and professional communicators are experts in making complex systems and worlds understandable to those who need to access them. However, both the concepts we are communicating about and the tools we are communicating with are changing at a rapid pace. To communicate effectively, we need our own knowledge and understanding to remain current, identifying best practice and learning from the experience of others.

Current Practices and Trends in Technical and Professional Communication is a valuable source of collective knowledge from our community of practice. Experienced practitioners and innovators (from the UK and international) are sharing what they know for the benefit of both the communicator and the end user.

The topics in the book cover important issues affecting the work we do (including globalization, localization and accessibility), and the tools and processes we can use to resolve some of the issues we encounter. Changes in technology are described, and ways of harnessing that technology are identified, including both current and future possibilities.

Whether you work in relative isolation, as the sole technical or professional communicator in a multidisciplinary team, or with other technical or professional communicators, you will find plenty in this book that is thought-provoking, interesting and useful.”

 

Delivering a digital strategy for Parliament – Interview with Rosie Hatton

From the Cherryleaf podcast: The UK Parliament is one of the oldest organisations in the world. So how do you deliver a strategy to a body that has over 700 years of content? Cherryleaf’s Ellis Pratt interviewed Rosie Hatton, Strategy Digital Lead at the Parliamentary Digital Service, to find out.

Topics covered:

  1. What is Parliament? 1’56”
  2. The content Parliament creates. 3’38”
  3. What is the PDS? 5’08”
  4. The I AM PARLIAMENT programme. 9’00”
  5. The PDS’s digital strategy framework, its assumptions and principles. 10’18”
  6. Having an open and agile digital culture in a traditional organisation. 13’08
  7. Working in a continuous interative process. 20’45”
  8. Sharing ideas with the Government Digital Service. 25’24”
  9. Where does the PDS’s content strategy fit within its digital strategy? 28’22”
  10. Tracking the impact of changes to laws on other laws. 37’01”
  11. The similarities between PDS and Open Source software projects. 41’55”
  12. Crowdsourcing a digital strategy. 43’30”
  13. Benefits management. 44’00”
  14. How to manage and sell change. 47’50”

Links:

People:

Example of API documentation portal using MadCap Flare

This post follows on from our Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI post. It shows screenshots of a test project we created. We used Swagger’s “petstore” example API specification as the source content. We didn’t spend any time modifying the stylesheets – these are just proofs of concept.

API documentation Home page

All the content uses the same navigation, and look and feel:

API documentation example in MadCap Flare - Home page

API reference information – single page

In this example, all the reference information is stored in a single file. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - Single reference page

API reference information – multiple pages

In this example, all the reference information is split into a multiple files. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel.

API documentation example in MadCap Flare - split into multiple pages

API reference information – resources and endpoints

API documentation example in MadCap Flare - post example

API documentation example in MadCap Flare - resource example

Incorporating content created by developers in Markdown

This shows an example of content created by a developer in Markdown format and imported into the project. This means the developers wouldn’t have to use Flare for any of their contributions, if they didn’t want to.

API documentation example in MadCap Flare - Markdown import

The advantage of this approach is it would give users a coherent and consistent user experience across all the API documentation.

See also: Cherryleaf’s API documentation writing services.

Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI

MadCap Software has published a whitepaper called The Definitive Guide to Creating API Documentation. It covers ten best practices for writers, and it describes how you can use MadCap Flare to implement these when you are writing API documentation. In this post, we’ll look at whether we can combine automatically generated REST API reference documentation with Flare, to create a web site that gives users a coherent and comprehensive user experience.

When writing REST API documentation, a lot of organisations use the API reference documentation that can be generated automatically from an API specification. Tools like Swagger UI can create web pages, which you can publish to a website.

The downside of this approach is the automatically generated REST API reference documentation typically has its own look and feel, and navigation structure. To the user, it often looks like there are two separate sites. One contains the reference information. The other describes what the API does, why you’d use it, how to get started, how to get an authentication key, how to get a “Hello World” response, tutorials, and so on. As soon as a website’s look and feel changes, there’s a cognitive load on the reader. They need to assimilate what has changed. It’s like trying to complete a task with two manuals open at the same time.

As a side project, we are looking at how you can create a site that has a cohesive set of documentation. In other words, make it easy for the user to move back forth between the automatically generated REST API reference information and other REST API documentation. You can do this with static site generators, but these often have limitations. By using MadCap Flare, you can include a site search, manage multiple versions, manage pro/lite products, re-use content, publish to PDF, manage localised content, manage synonyms, and avoid inserting scripts into pages that only the original creator understands. MadCap Flare is good at scale, dealing with the messier problems that often affect documentation.

The objectives are:

  • Include REST API reference content automatically generated from the API specification. Whenever the REST API specification is updated, that content automatically updates itself in the Flare project
  • Include content written by developers in Markdown. In other words, let the developers write in their preferred authoring environment. If a developer updates that content, that content automatically updates itself in the Flare project.
  • Use Flare to manage the content, and do the messy stuff like search, linking, pdfs, tables, flowcharts etc.
  • Publish web pages that provide a comprehensive and coherent user experience.

Can this be done? Yes. The main issue is whether to keep all the automatically generated REST API reference documentation as a single web page, or split each resource into separate topics (i.e. separate web pages). We’re currently looking at the best way to do both. When we’ve settled on the best approach, we’ll publish some examples on the Cherryleaf blog.

Take part in the Cherryleaf 2017 European salary survey

It’s been a while since our last survey of technical communicator salaries. So we thought it was time we conducted a new one.

We have contracted with QuestionPro, an independent research firm, to field your confidential survey responses. All responses will remain confidential and secure.

The questions will help us learn if salary levels correlate to factors such as age, gender, education, or levels of seniority.

We’ll publish the results on this blog.

Please use this link to complete the online survey:

Take part in the Cherryleaf 2017 European salary survey

Help through AI, Help like Facebook

Reviews of two presentations at the UAEurope 17 conference.

Kristof Van Tomme (Pronovix). Software support and Artificial Intelligence.

Pawel Kowaluk (3di Poland). Knowledge Feed: Make your Online Help More Like Facebook

Interspersed with interviews from at the UAEurope 2017 conference:

Dr Tony Self. HyperWrite

Willam van Weelden. Adobe

Mike Hamilton. MadCap Software.