Ideas for improving the documentation?

[Vincent38]

Good morning

I am opening this post following another of my posts, where, after a remark concerning a problem (for me) with the documentation, m cardon told me about a question that tranquil it is asking internally concerning the screenshots in the documentation (and the difficulty of keeping them up to date) and offered me to give him my opinion.

So I'm putting it here, so as not to clutter my original post and to get other opinions?
At worst, it will allow me to know if it's just me who's having trouble with the current documentation

Regarding the screenshots, in my opinion, you could easily remove a large portion of them.
Screenshots are fine when the documentation is aimed at a non-expert audience, but given the product you offer, the majority of your clients must be IT administrators, therefore people used to reading technical documentation, often with few screenshots. Especially since
this product aims to replace Microsoft tools, and its installation is recommended on Linux, a large portion of users must be Linux veterans, having absorbed tons of "man" pages, which are purely text-based.

There are many screenshots in your documentation that are often just illustrations of something obvious; the text explanation is perfectly clear, the screenshot adds nothing.
For example, in section "1.4.3", the text "In the WAPT Console go to Tools ‣ Build certificate" is sufficient in itself.
However, to illustrate when there are many options, they can be useful.
For example, in section "1.6.3. Build," in my opinion, the first screenshot is unnecessary, the second optional, the third useful, and the fourth and fifth unnecessary.

A few screenshots are good for "breaking up" the text, but the problem here is that there are so many screenshots that when you're looking for specific information in the documentation, it's tedious because you have to scroll a long way down the page before reaching the section you're interested in. Especially since (at least in my case), the interspersing of so many images makes it difficult to find the title corresponding to what I'm looking for.
When there's 80-90% text, you can scroll quickly, only skimming the bold headings, which makes it easy to find what you're looking for.

What's surprising is the stark difference between the WAPT documentation and the one you're offering for Samba AD, which is clear, precise, and easy to use.

One of the best documentations I've ever read (and that I use often) is for WatchGuard firewalls. The sheer number of options and explanations is incredible, yet they've managed to keep it relatively clear.
https://www.watchguard.com/help/docs/he ... front.html

But having had to write technical documentation myself a few years ago (and getting absolutely hammered on the first draft ), I know it's far from easy, especially when the documentation concerns a product you designed yourself. It's difficult to put yourself in the shoes of someone discovering it for the first time; we tend to forget things that seem obvious to us.
And all the more so since your product is already several years old, so the documentation must have grown over time.

An idea (perhaps unrealistic, but it's possible ): take on an intern for one or two weeks to revise the documentation with someone who has an external perspective?

In any case, WAPT is a great product (and your version of Samba AD too) ), powerful and very useful, thank you!