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

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.

Using MadCap Flare 2017 for company procedures – Quick review

We’ve been setting our staff the challenge of using some of the popular Help Authoring tools to create online company documents.

We asked them to make some notes on the applications they used. Here are some of the notes relating to MadCap Flare 2017:

“You soon become aware it’s a really powerful tool. Is this actually a CMS?

It’s a breeze to import content. The authoring environment is nice and easy to use. It’s easy to jump into the HTML if you want to. Easy to make global changes. 🙂 You can carry on working in Flare while it’s building the output files.

It complex, though. To make a change to the look and feel, I’d ask myself do I change the skin, the master page, or the stylesheet? When you know where the setting is, you can make lots of tweaks and changes.

The web pages it creates seem to load really quickly. The only downside of publishing is it creates a lot of subfolders. I had to manually create the folders on the website. That took a while to do.”

Assessing the potential savings from single sourcing

One of the main benefits from single sourcing is the ability to reuse existing content. Different departments can avoid duplicating work, which means they can save time and money.

Unfortunately, it can be difficult to quantify these savings before you move to an authoring or content management system that enables you to single source. Analysing all the existing documents in a business can be overwhelming, which means often organisations only quantify the savings after the single sourcing content management system has been implemented.

There are a few software applications that can help you analyse your existing content and determine how much duplication exists. You get a sense of how much time and effort was wasted in the past, which is a pretty good indication of how much waste you’d avoid in the future.

Continue reading “Assessing the potential savings from single sourcing”

Super MadCap quite fantastic; are other tools atrocious?

With the imminent release of DITA support in MadCap Flare, will competing Help authoring tools (HATS) suddenly seem inadequate to the task of technical writing?

Where does this leave Adobe’s RoboHelp?

I suspect it will be difficult technically and commercially (Adobe also owns FrameMaker) for Adobe to add DITA support into RoboHelp.

If writers are collaborating on a project or if a Help system needs be localised into foreign languages, then RoboHelp and other HATS may well lose out to Flare.

However, if a sole author just needs to write a straightforward Help File, then many may not feel the need to change from the tool they use today.

So what would you do if you were Adobe?

I wonder if Adobe will choose to compete with MadCap in other ways. RoboHelp could become more of an online training, performance support, tool. Also, Adobe could bundle RoboHelp with FrameMaker at a price that makes Flare seem very expensive.

This, of course, may be all academic if the DITA standard isn’t taken up by more authors.