The whole point of an editor is to make it easy to do complex formatting. One might say that Flare is “idiot-proof”, but I prefer to say that Flare helps protect a tech writer from the inevitable distractions faced during a typical day at the office. Although I am sure there are ways to mess your project up, it is much harder to do so when choices are guided and constrained. By using the appropriate wizard, you can create a new project, import a project, create or edit a stylesheet, export a project in one fell swoop, or other important tasks. I am a longstanding command-line and text-editor devotee, but even I have to admit that a good GUI-based system is more effective and efficient in many circumstances. I do have a good semantic understanding of XML, HTML, CSS, and JavaScript, which came in very handy so that I could see what Flare was doing.įlare’s wizard-based system is a joy to use. Although I have tried out various XML editors, this beta trial of MadCap Flare was my first serious effort in a long time to use a tool to create online help. To that end, I tested Flare’s conversion capabilities with various documents, help systems, and books, which had been created over a long period of time in a variety of formats.įrom time to time, I have edited web projects using tools like Notepad ++. I have been beta-testing MadCap Flare 9 as a TechWhirl assignment, but also with an eye for making a software tool choice for a company that has a huge quantity of complex legacy content. Eons ago, I used RoboHelp and various other editors. It also includes a second API reference example, where the content is displayed in HTML format.In the last job I held that required web output, I used Visual InterDev, as I was creating a program interface, not online help. The Markdown file has been imported, but no amendments have been made to the look and feel. Here is screenshot and a link to an example Help file, where the OpenAPI file has been imported into Flare, using the Markdown import. See also: Cherryleaf’s API documentation writing services. The advantage of this approach is it would give users a coherent and consistent user experience across all the API documentation. This means the developers wouldn’t have to use Flare for any of their contributions, if they didn’t want to. This shows an example of content created by a developer in Markdown format and imported into the project. API reference information – resources and endpoints Incorporating content created by developers in Markdown There’s more work required on the stylesheet and Flare master pages in order to improve the look and feel. We set the Flare project up in a way that this content updates automatically whenever the API specification file changes. In this example, all the reference information is split into a multiple files. API reference information – multiple pages In this example, all the reference information is stored in a single file. API documentation Home pageĪll the content uses the same navigation, and look and feel: API reference information – single page 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. It shows screenshots of a test project we created. This post follows on from our Creating an API documentation portal with MadCap Flare and Swagger/OpenAPI post.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |