How We Built Our Own TestBench
...and why you don't need a whole microscope just to test firmware
Do user manuals still have a place in the age of AI?
Reading a user manual is often seen as the last, sometimes even humiliating, option. With new technologies, however, we can often replace it with "Googling" and today also with AI prompt. Does it even make sense to create user manuals these days?
Proper Design
My colleague designs APIs for controlling electron microscopes in such a way that the user does not need a manual to perform an action. The names of all functions and methods are often a bit longer, but they perfectly describe what they do.
UX should not be a forbidden word, and a UX designer should not be seen as someone who just paints buttons. If everything is clear and understandable, users will use our application much more gladly and efficiently. Proper user interface design can thus be the key when deciding which application to use or purchase. Users are, after all, humans with emotions, and if we annoy them or back them into a corner right from the start, they may never come back.
How to Create Manuals
Just like the application itself, the manual should be user-friendly. Users should be able to easily find what they are looking for—whether through links or search.
We should avoid complex phrasing and understand that the person on the "other end" may often be someone struggling to grasp how the thing works. Or, conversely, they may understand the subject matter but cannot navigate through the abbreviations and terms we have used.
The structure of the manual itself, or its individual pages, is the key. I consider the use of basic formatting—such as headings, paragraphs, or bullet points—as a standard. Sometimes, a table or an image is more appropriate than a paragraph.
However, I would be cautious with the use of images. While a picture is worth a thousand words, it can also bring unexpected complications. Many applications and websites today offer dark and light modes, the ability to use different color schemes, or even complete UI customization. An image of the application in the manual may therefore not correspond to reality at all.
How detailed should a manual be? For some, a simple prompt like "open the file" is enough, while others need to be guided step-by-step: "click the 'File' menu in the application's top navigation and then select the 'Open' option." Establishing the line between simplicity and purpose will always be difficult. It is best to base it on our user profiles or general conventions. However, we must keep in mind that we are "IT people" and our perspective in this regard can be very skewed.
Sustainability
Another problem related to images in manuals is maintainability. A simple change to a button label, for example, can result in the need to replace dozens of images throughout the manual. Therefore, I would recommend using images only when strictly necessary—for instance, to explain data flow within the application or the interconnection of individual modules. I would suggest avoiding UI screenshots altogether. Notice, for example, that documentation from companies like Google or Microsoft contains almost no images. Their user interfaces change so frequently that maintaining images would be virtually impossible.
The manual itself should be well-designed for easy maintenance. Correcting a typo should not be a process that occupies one person for half a day.
Documentation
If we treat the user manual as an integral part of our product’s documentation, it significantly increases its importance. Ideally, its source should be part of the project repository or the documentation system.
And who is responsible for writing the manual? Team members often pass this responsibility around like a "hot potato." However, it should be the responsibility of the entire team. Creating and managing the manual should be a regular part of the development process.
It is also important to remember that an outdated manual is a bad manual. In our team, for example, updating the manual is a mandatory part of the delivery, just like providing the source code and tests.
Do we need manuals when we have AI?
Yes. And we need them much more than ever before. AI learns from data, and a user manual is an excellent data source. As developers, we should take this fact into account. We should create user manuals in a way that allows AI to learn from them or include them in its context. Ideally, the user manual should be machine-readable—for example, in HTML or, preferably, Markdown format. However, today's AI agents can handle other formats as well; in the case of user manuals, this is most often a PDF.
The importance of manuals
In my opinion, the user manual is an essential part of the software. It should be high-quality, sustainable, and beneficial, thereby meeting the same criteria as the software itself.
It should not be a burden to developers, and developers, in turn, should consider its form. It should be a living document (yet "frozen" for a specific version of the application), which can be further utilized, for example, through AI.
