Apro questo post dopo un altro mio post, in cui, dopo un'osservazione riguardante un problema (per me) con la documentazione, m cardon mi ha parlato di una domanda che sta ponendo internamente riguardo agli screenshot nella documentazione (e alla difficoltà di mantenerli aggiornati) e mi ha offerto di dargli la mia opinione.
Quindi lo metto qui, per non appesantire il mio post originale
e per avere altri pareri?Nella peggiore delle ipotesi, mi permetterà di sapere se sono l'unico ad avere problemi con la documentazione attuale
In ogni caso, WAPT è un ottimo prodotto (e anche la tua versione di Samba AD)Per quanto riguarda gli screenshot, a mio parere potreste facilmente eliminarne una buona parte.
Gli screenshot vanno bene quando la documentazione è destinata a un pubblico non esperto, ma dato il prodotto che offrite, la maggior parte dei vostri clienti saranno amministratori IT, quindi persone abituate a leggere documentazione tecnica, spesso con poche schermate. Soprattutto perché
questo prodotto mira a sostituire gli strumenti Microsoft e la sua installazione è consigliata su Linux, una buona parte degli utenti saranno veterani di Linux, che avranno assimilato tonnellate di pagine "man", che sono puramente testuali.
Ci sono molti screenshot nella vostra documentazione che spesso illustrano semplicemente qualcosa di ovvio; la spiegazione testuale è perfettamente chiara, lo screenshot non aggiunge nulla.
Ad esempio, nella sezione "1.4.3", il testo "Nella console WAPT vai su Strumenti ‣ Crea certificato" è sufficiente di per sé.
Tuttavia, per illustrare quando ci sono molte opzioni, possono essere utili.
Ad esempio, nella sezione "1.6.3. Crea", a mio parere, il primo screenshot è superfluo, il secondo facoltativo, il terzo utile e il quarto e il quinto superflui.
Alcuni screenshot sono utili per "spezzare" il testo, ma il problema è che ce ne sono così tanti che, quando si cercano informazioni specifiche nella documentazione, la ricerca diventa tediosa perché bisogna scorrere parecchio la pagina prima di raggiungere la sezione di interesse. Soprattutto perché (almeno nel mio caso) l'alternanza di così tante immagini rende difficile trovare il titolo corrispondente a ciò che si sta cercando.
Quando l'80-90% del testo è costituito da immagini, si può scorrere velocemente, dando solo un'occhiata ai titoli in grassetto, il che rende facile trovare ciò che si cerca.
Ciò che sorprende è la netta differenza tra la documentazione di WAPT e quella che offrite per Samba AD, che è chiara, precisa e facile da usare.
Una delle migliori documentazioni che abbia mai letto (e che uso spesso) è quella dei firewall WatchGuard. L'enorme numero di opzioni e spiegazioni è incredibile, eppure sono riusciti a mantenerla relativamente chiara.
Italiano: https://www.watchguard.com/help/docs/he ... front.html
Ma avendo dovuto scrivere io stesso della documentazione tecnica qualche anno fa (e avendo ricevuto critiche feroci sulla prima bozza
E questo vale ancora di più se il tuo prodotto ha già diversi anni, quindi la documentazione deve essere cresciuta nel tempo.
Un'idea (forse irrealistica, ma possibile
), potente e molto utile, grazie!