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:
- Generate the API reference documentation in HTML format from the OpenAPI specification file. This could be generated automatically each day.
- 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.
- 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.
- 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
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.”
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 Two”
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 “MadWorld 2016 Conference Review – Day One”
Cherryleaf’s Ellis Pratt will be speaking again at MadCap Software’s conference on technical communication and content strategy conference. MadWorld 2016 will be held between the 10th and 12th April 2016 at the Hilton San Diego Resort and Spa, in San Diego, California.
Continue reading “Ellis will be speaking at MadWorld 2016”
Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.
For all those issues, SharePoint may still have its place – for managing documentation projects.
Continue reading “SharePoint for documentation projects”
Once again, I enjoyed immensely Madcap Software’s MadWorld conference in San Diego.
This was Madcap’s second annual conference, building on the success of MadWorld 2013.
Continue reading “MadWorld 2014 conference review”
MadCap Software hosted their first ever conference, MadWorld 2013, last week, which I attended as an invited speaker. Here are my initial thoughts and reflections on the second day.
Continue reading “MadWorld 2013 conference review – Day 2”