Back to Blog
Madcap flare6/8/2023 ![]() You can do this with static site generators, but these often have limitations. 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. It’s like trying to complete a task with two manuals open at the same time.Īs a side project, we are looking at how you can create a site that has a cohesive set of documentation. They need to assimilate what has changed. 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. To the user, it often looks like there are two separate sites. The downside of this approach is the automatically generated REST API reference documentation typically has its own look and feel, and navigation structure. Tools like Swagger UI can create web pages, which you can publish to a website. When writing REST API documentation, a lot of organisations use the API reference documentation that can be generated automatically from an API specification. ![]() 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. 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. I’d encourage anyone looking to enhance their schools technical communication program to contact MadCap Software today.įor more information, check out our MadCap Scholar Program section.MadCap Software has published a whitepaper called The Definitive Guide to Creating API Documentation. Content created in Flare can be published to any number of channels, including complex digital print, desktop publishing, Web-based, or mobile platforms-so it was a great avenue to introducing material such as XML and topic based authoring. Using Flare's patented dynamic XML editor, technical writers were able to focus on content-without any XML programming knowledge. We found schools from around the world clamoring for assistance with their individual programs. The response we received was resounding and the impact was immediate. How could we help? By providing the students the tools necessary to understand technical communication in today’s workplace-for no cost, that’s how! Understanding the depth and complexity of software-and giving them the opportunity to work with Flare and the rest of the MadPak early on in their student life has proven to instill best practices that are essential to a student's success with a long-term career in the technical communication industry. As a software company, we quickly became committed to helping provide students with the skills and knowledge they need to create and manage today’s technical content. Word was the primary “editor” used-and most of their education was around the concepts and practice of technical communication-not working with XML, CSS, or single sourcing. Most programs were providing students with outdated versions of software that generally only created a single output type (DITA, PDF, or. The programs weren’t well funded, and their students were graduating without ever having practical experience working with a modern authoring program. The concepts and methods they were teaching certainly varied based on the strength of the curriculum-but a constant was that the technology and tools the students were mandated to develop with were generally outdated and limited. ![]() In our work with various educational institutions both abroad and here in the United States, we were seeing consistent trends in the groups we were talking to. For this month’s Notebook guest post, I wanted to take the opportunity to showcase an area of #TechComm that I’m very excited about: The MadCap Scholar Program Today we bring you another guest blog post from MadCap Software, written by Jose Sermeno, a product evangelist at MadCap.
0 Comments
Read More
Leave a Reply. |