Creating a User Guide for the Vital Synthesizer

For anyone interested, I wanted to share a bit about the process of creating a user guide for the Vital synthesizer.

Why did I embark on this project?

I'm a technical writer, and many of the jobs I apply for require a portfolio or examples of work. My professional output thus far has been almost entirely proprietary and not publicly accessible, so I needed to find something to document that would also be a learning opportunity, genuinely useful, and interesting enough so it wouldn't be an agonizing task on top of my day job.

Why Vital?

I love music and music technology, so I was searching for something in that area when I stumbled across Vital which is luckily open source. It has no code documentation, and the user manuals available were not comprehensive. I felt I could do a much better job.

What have I learned?

It's been a very long time since I've created a user manual, and this is the first time I've done so with AI tools available. ChatGPT (o1 Pro as well as the brand-spanking-new o3-mini-high with Deep Research) was handy for single code docs and general topic summaries, but it was almost useless for actually authoring the manual. The responses I received were riddled with "hallucinations" and often contained inaccurate information. Perhaps I don't yet know how to leverage AI's graphics capabilities, so it played no role in that. All graphics were painstakingly created in Adobe Illustrator.

Although I'm an enthusiast, I've never authored anything about audio synthesis before and only have minimal formal training in it. It was challenging to get up to speed on how all the synth's components work. This was also the first time I couldn't collaborate with anyone involved in the product's creation, so I had to do a lot of digging to answer my questions.

The image callouts are also non-standard, since they contain a lot of information, rather than just numbers referencing text sections. I felt this was the best way to present the information, as it removes the cognitive load of matching each number to a separate explanation. This is a desktop product, so I assume most users will have a large enough screen to view the callouts.

The scope of the project changed multiple times during its creation. Initially, I tried to fork the repo and embed everything in-app with a help window and tooltips. However, lacking experience with JUCE and OpenGL, and only having had a little bit of C++ during college, I faced debugging issues I couldn't resolve quickly. At the same time, I was developing a reference section on general synthesis topics, building a chatbot trained on the user guide, and adding extensive tooltips throughout the manual. I had a deadline—to have it ready for job applications before my current contract ends—so narrowing the scope was essential!

What's next?

We'll see, but I would like to complete what I already started which is the following:

• Vital:
  • Code docs
  • Video tutorials and audio examples
  • Chatbot trained on the user manual and videos
  • Tooltips to be added throughout the manual
• General synthesis:
  • Glossary with examples