These technical communication Venn diagram stickers have arrived. If you contact us,, and you live in Europe, we will post some out to you.
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:
Further work could be done to improve the outputs:
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.
“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.”
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.
Our latest podcast – a round up of recent news in technical communications.
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.
All the content uses the same navigation, and look and feel:
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.
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.
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.
The advantage of this approach is it would give users a coherent and consistent user experience across all the API documentation.
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:
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.
Recording from UAEurope 2017 conference.
With many software developers now spending their time developing APIs, there’s an increasing demand for API documentation writers.
It’s a fast changing field, with emerging information design patterns and authoring tools. It’s also different from end user documentation, and this means many Technical Communicators are uncertain if and how they should migrate to these roles.
REST API documentation training course: