I don’t really like writing documentation, and I can count with half a hand, the number of engineers I’ve worked with that truly and honestly liked to do it. But, if there is something I dislike even more, is having to answer the same questions over and over about how to use my app or script.
Due to that (in your face positive motivation) I’ve spent some time learning a few tricks on how to create documents easy to read, and easy to write, with out having to spent much time on them, and I’m willing to share them with you.
Set the Course Sailor
Just like when sailing in the middle of the sea, you need to know in which direction to point your boat. Or you could end up messing it up big, really big. When writing docs you need to know which is your target audience.
Your target audience will define how technical you can get on your explanations, and will give you a better idea of how people will interact with your project. For instance, if you’re writing for developers, you may want to include more technical details and even some insight of internal design, and expect them to make a more advance usage of it. On the other hand, when writing for people how “doesn’t speak dev” ( like a marketing team), you’ll have to reduce the number of technical words and expect a more basic usage of it.
Do not try to… let me emphasize that, DO NOT try to create a document for both, technical and non-technical audience. It’ll be boring for technical folks, and confusing for non-technical ones. If you need to target both, create separated documents.
Once you know who’s gonna be reading your doc, its time to sit down and start writing.
The IBM Pattern
No, this is not the “International Business Machines” pattern, its the “Intro-Basic-More” pattern, based on the KISS principle (Keep It Simple, Sailor). What is that IBM thing? Is a simple mnemotechnic I use to remember that any documentation (like a README file) should have the following:
- An Introduction section, explaining what the tool/service/project is about. It has to be concise and brief. Don’t overthink it, one sentence or two at top, and that should be it. You can also include the (one-liner) install command here.
- The Basic Usage section should show the users how to achieve the most probable reason why they want to use this tool/service/project, and only that. If you’re writing a doc for grep, the basic usage is
grep 'skywalker', if you’re writing a doc for curl, the basic usage iscurl starwars.com. Give them what they came to find right away. - Last but not least, More Questions. This section should present a way for the reader to find more information if the basic usage is not enough. It could be a list of FAQs1, how to use the “help/usage” command, a link to a more detailed document (like a Swagger based site), or a way to contact you (not recommended).
By following this patter you’ll make sure that anyone who reads it will get a clear idea of what you project is for and what it does, how to make a basic usage of it, and how to get more info if needed.
VHS
Some of you may say “Sounds great Santi, but how can I document the basic usage if I don’t like documenting”. Argh! What a predicament, but I got you covered.
There is this tool I’ve been using for showing users how use my scripts and apps, with little to no effort from my side. It’s called VHS (yes, as in Video Home System ) and it allows you to create GIFs of commands running on a terminal, from the terminal. Is not a recording app (tho it can do that as well), it’s a GIF generator.
You can instruct VHS to create a GIF running your app. And update that GIF automatically on every release. So you’ll get your documentation up to date effortlessly.
For instance, this is a script I wrote for dev teams to create a couple of Kubernetes manifest files. It has many options to customize those manifests, but for most common usage, which is a new app for development, this is more than enough:
Get Your Own Boat
Let me show you how to use VHS by following the IBM pattern.
VHS Intro
This tool allows you to create terminal GIFs as code for integration testing and demoing your CLI tools.
Install it by simply running: brew install vhs. Check for more install options here.
Basic Usage
- Create a new vhs_demo.tape file with the following content:
Output vhs_demo.gifRequire echoSet Shell "bash"Set FontSize 16Set Width 800Set Height 450Type "vhs vhs_demo.tape"Sleep 1sEnterSleep 5s
Change the “Type” command with your own.
Execute VHS to generate the GIF:
- Get the vhs_demo.gif file generated on the same folder.
More Questions
Run vhs -h to see all the options available, or check the official docs to learn more about VHS and its advance usage.
Raise the Sails
Following this pattern, and using VHS for adding examples and expected outputs has helped me a lot to reduce the number of times people needs to come to me for help for common tasks. Hope it helps you too.
What do you think about it? How do you write your docs? I really wanna know 
- Frequently Asked Questions
︎
Top comments (2)
The idea of using VHS for documentation really sparks my interest! It's such a unique and creative approach that stands out from the traditional methods. I'm definitely inspired to give it a try after reading about it. Thanks for sharing this cool concept!
it has really helped me a lot to show colleges how to use certain tools and scripts, and what kind of output to expect. Hope it helps you to :D