This guest blog post was written by Lisa Hamilton, Experience Content Manager at Axiom Law (axiomlaw.com). Lisa is a certified MadCap Advanced Developer and content professional who manages user content and communications for legal technology and cloud solutions. She is also a contributing member and meetup organizer for Write the Docs (an international technical writing community).
Running MadCap Flare on a Mac via Amazon WorkSpaces is so easy that until MadCap Software asked me to write this article, I forgot I was doing it. And that’s saying a lot because while I am a self-proclaimed content nerd, I am not a geek. I like to design great content consumer experiences and leave the technical details to those who enjoy that sort of thing. So, if you’ve been hesitant to get Flare going on your Mac because it seems complicated, I can assure you, it is not.
Setting Up MadCap Flare on a Mac
Shortly after joining an all-Mac design team in a content role, the team was seeking a content authoring solution to develop our documentation websites. I was sure that MadCap Flare was the solution our team needed. However, I needed to find a way to run Flare on a Mac, specifically a MacBook Air. . One email to MadCap Software later, I was relieved to learn that it was in fact possible, by way of a virtual Windows machine. I emailed our IT department and I learned that we already had a managed, secure virtual desktop solution available -- Amazon WorkSpaces. Within a day I was set up with my own Workspace, installed Flare on it myself, and built my first Flare-on-a-Mac help project. It worked exactly the same as building Flare projects on a PC.
With a small lift from Engineering, we bound our project to Git, set up a Flare build license to automate builds and publishes through GitLab-runner, and secured the help output through private S3 buckets that are exposed through our apps (users must be signed in to the apps to access the help content). Since then, we have dual-bound to MadCap Central to take advantage of cloud-based reviews, internal sandbox sites, and analytics.
Fast forward two years, and here’s what a day in the life of Flare on a Mac via Amazon WorkSpaces looks like.
Authoring and Publishing
I like to do most of my work on the Mac and save WorkSpaces for Flare and MadCap Central. It’s just a clean way of working with your native Mac apps and keeping things simple.
On any given day I use the productivity tools and apps that I’m documenting on my Mac, and then copy content straight from there to Flare on WorkSpaces. Command-Tab and 3-finger swipes make it easy to toggle between all apps on both sides.
No Ctrl-Alt-Del keyboard command on the Mac is no problem. When you need to unlock the Windows desktop on WorkSpaces, there’s a menu option for that.
When I’m ready to publish output to our staging or production environments, I use the Source Control ribbon in Flare to push changes to our git repository. The continuous integration and continuous delivery (CI/CD) pipeline takes every commit to master and builds the documentation on the Workspace. After building, CI/CD syncs the output to the staging Workspace docs bucket. Promoting to production is done by merging master into the production branch, with CI/CD doing the same thing but for the production Workspace docs bucket.
If I want to publish to MadCap Central, which we use for SME cloud reviews and sandbox sites, I push to MadCap Central instead of git, and then it’s business as usual in MadCap Central, which is easily accessed from the Mac or Workspaces side since it is a cloud-based application that runs in the browser
Adding Images
My favorite path for getting screenshots into Flare on WorkSpaces from a Mac is by doing a Command-Shift-4 to copy a region of my app, and then swiping over to WorkSpaces and pasting it directly into the Flare topic, naming and saving it to the project as part of that same interaction.
It’s also super easy to annotate the image in Preview on the Mac before doing the copy and paste to Flare. If I want to further revise the image, I do that with MadCap Capture after I’ve added it to the topic.
Moving and Sharing Files Between Mac and WorkSpaces
Cloud storage is an easy way to move and share files between the Mac and WorkSpaces. But it’s not the only way. You can also:
- Copy and paste text and images between Mac and Workspaces.
- Slack files to yourself from Mac to Workspaces and back.
- Email files to yourself on one side and pick them up on the other.
Performance
In the two years we’ve been running Flare on a Mac via WorkSpaces, we’ve had 0 Help site downtime, and only two instances where the Workspace had to be restarted (generic “unable to sign in to Workspace” error), each instance resulting in a 30-minute authoring disruption while the Workspace came back online, and a quick call to have MadCap Software release the license after Flare reconnected to the Workspace.
Set it and Forget it
I often refer to Flare on a Mac via WorkSpaces as a set-it-and-forget-it proposition. That’s definitely been my experience. It was easy to set up with a small lift from IT and Engineering, has required minimal maintenance, and adds no overhead or complexity at all to the author experience.
Are you using Flare on a Mac with WorkSpaces or something else? Have tips or best practices to share? General questions about running Flare on a VM? Request access to join the MadCap Flare Slack Community and visit the #flare-on-vm channel.
