Creating Shortcat’s help manual — a technical documentation case study
How we created minimally viable documentation for a novel macOS app
Shortcat, a macOS app that enables keyboard-only operation for other apps, recently contracted me to create its technical documentation. The primary goal was to create a minimally viable version of the documentation in time for his talk.
chendo, the founder of Shortcat, had a presentation on the app a month later. We were on a deadline.
During the contract, I got on some calls with Chendo to ask various questions. I’ll include some of these q’s here because they detail how we came to specific conclusions.
Derick: Founders rarely realize the importance of documentation for their products. So what made you decide to find someone to help you write your docs?
chendo: I understand that writing good documentation takes time, and I didn’t have the capacity. I’m actively working on a brand new re-write of the app, preparing for a talk, and I need an expert to help me get the docs in shape.
This article will explain exactly how we got Shortcat’s documentation into great shape in less than a month.
What is Shortcat?
Shortcat is a macOS app that enables keyboard-only operation of various apps on your Mac. It lets you click buttons, focus on text fields, switch windows, and more with only your keyboard.
You can search for elements (links, buttons, headlines, etc.) on any application and conduct an action, like clicking or focusing, on that element.
I’d compare Shortcat to the native search function built into browsers that you can access using CTRL + F and Macro creation software. Although, it’s not a complete 1-to-1 comparison because Shortcat allows you to conduct actions on the elements you find with your search.
For example, you can search for Promotions while browsing Gmail and press Enter on your keyboard to navigate that section.
It’s the perfect app for keyboard warriors.
Derick: What was the primary goal you wanted to achieve with Shortcat’s technical documentation?
chendo: Shortcat is a novel product that many people wouldn’t have seen before. Trying to explain its capabilities natively in the app is challenging. Having detailed textual that can answer most people’s questions is good.
Shortcat is an application that works with a variety of other apps, and upon the first installation, you’ll see a screen like this:
It’s an application that’s not immediately comparable to any other app. So we needed a very concrete plan of attack for how to approach the app’s documentation.
The documentation’s goals
Right from the beginning, we knew this thing needed to be heavily example-focused. As a result, we littered the docs with real-world example GIFs that show users how to use the app.
This is the structure that we decided on for Shortcat’s documentation:
⏎ Introduction
⏎ Getting Started
⏎ App Compatibility
⏎ Configuration Options
⏎ Features
⏎ Search
⏎ Actions
⏎ Selection
⏎ Common Issues
⏎ Common Use CasesPages like Introduction and Getting Started are required and self-explanatory. But, there are a few pages that we should dive into, like Common Issues and Common Use Cases.
Shortcat has 3 primary features: Search, Selection, and Actions.
The Features page gives a general overview of each feature and some helpful GIFs. So when the user scans this page, they’ll already get the gist of how to approach the app.
Its custom search syntax allows you to boil down your search to just what you need quickly. You can also do various actions that simulate clicks and window switching, all accessible from the keyboard.
Common Issues and Common Use Cases pages are critical in Shortcat’s case.
Due to its novel nature, including a page laying out common issues makes sense. These aren’t bugs, but perhaps misunderstandings with the app due to misconfiguration or it not working correctly with another app, for example.
If you already have users emailing you or tweeting you with users, it’s a great place to start with the gathering of which issues to focus on first.
That way, users have a single location to visit if they encounter anything while using the app.
The everyday use cases page is what I gathered after exciting ways to use Shortcat based on what I saw on Twitter and my conversations with Chendo. A few interesting examples on this page showcase how to use Shortcat in the real world.
A Common Use Cases page is vital for an app that is supposed to be used together with many other applications.
Implementing the documentation with Docusaurus
After deciding on the documentation structure, we went with Docusaurus as the documentation framework of choice.
Derick: Why did you choose Docusaurus as your documentation framework of choice to create your documentation?
chendo: Many documentation sites are already using it. It provides good search, and you don’t have to worry about custom styling. With built-in JSX support, I’m able to do more complicated things on the docs, and having the flexibility of both JSX and markdown is very nice.
Although we didn’t fully utilize all the features that Docusaurus has, Chendo is now available to build upon this MVP version of the documentation. In addition, if he wants to expand upon it with custom functionality rather than just content, Docusaurus makes that easy.
Also, the amount of time saved with Docusaurus’ out-of-the-box solution can’t be understated. We essentially just wrote a bunch of Markdown files, and Docusaurus compiled it and took care of the rest.
Conclusion
Ultimately, Shortcat is an interestingly novel application that looks simple when you first open it. Still, we approached it the way we did because many users would not have seen an application like this before.
Thank you for taking the time to read this case study, and thank you to Chendo for the opportunity to let me document your application.
Ready for results like these?
Solidstate is a technical content marketing agency that helps software companies and technical education companies grow with writing. Ready to get results like these for your company?
Fill in the form below and let’s get started.
