Abro este post a continuación de otro de mis posts, donde, después de un comentario sobre un problema (para mí) con la documentación, m cardon me comentó sobre una pregunta que tranquilo está haciendo internamente sobre las capturas de pantalla en la documentación (y la dificultad de mantenerlas actualizadas) y me ofreció darle mi opinión.
Así que lo pongo aquí para no saturar mi publicación original
¿Y para obtener otras opiniones?En el peor de los casos, me permitirá saber si soy el único que tiene problemas con la documentación actual
En cualquier caso, WAPT es un gran producto (y su versión de Samba AD también)En cuanto a las capturas de pantalla, en mi opinión, se podría eliminar fácilmente una gran parte de ellas.
Las capturas de pantalla son útiles cuando la documentación está dirigida a un público no experto, pero dado el producto que ofrecen, la mayoría de sus clientes deben ser administradores de TI, personas acostumbradas a leer documentación técnica, a menudo con pocas capturas de pantalla. Especialmente porque
este producto pretende reemplazar las herramientas de Microsoft, y su instalación se recomienda en Linux, una gran parte de los usuarios deben ser veteranos de Linux, que han asimilado muchísimas páginas "man", que son puramente textuales.
Hay muchas capturas de pantalla en su documentación que a menudo son solo ilustraciones de algo obvio; la explicación textual es perfectamente clara, la captura de pantalla no aporta nada.
Por ejemplo, en la sección "1.4.3", el texto "En la consola WAPT, vaya a Herramientas ‣ Generar certificado" es suficiente por sí solo.
Sin embargo, para ilustrar cuando hay muchas opciones, pueden ser útiles.
Por ejemplo, en la sección "1.6.3. Generar", en mi opinión, la primera captura de pantalla es innecesaria, la segunda opcional, la tercera útil y la cuarta y la quinta innecesarias.
Unas cuantas capturas de pantalla son útiles para intercalar el texto, pero el problema es que hay tantas que, al buscar información específica en la documentación, resulta tedioso, ya que hay que desplazarse mucho hacia abajo antes de llegar a la sección de interés. Sobre todo porque (al menos en mi caso), la intercalación de tantas imágenes dificulta encontrar el título correspondiente. Cuando el
texto ocupa entre un 80 % y un 90 % del texto, se puede desplazar rápidamente, leyendo solo los títulos en negrita, lo que facilita encontrar lo que se busca.
Lo sorprendente es la enorme diferencia entre la documentación de WAPT y la que ofrecen para Samba AD, que es clara, precisa y fácil de usar.
Una de las mejores documentaciones que he leído (y que uso con frecuencia) es la de los firewalls WatchGuard. La cantidad de opciones y explicaciones es increíble, y aun así han logrado que sea relativamente clara.
https://www.watchguard.com/help/docs/he ... front.html
Pero habiendo tenido que escribir documentación técnica hace unos años (y sufriendo muchísimos problemas con el primer borrador
Y más aún si tu producto ya tiene varios años, así que la documentación debe haber evolucionado con el tiempo.
Una idea (quizás poco realista, pero posible
), potente y muy útil, gracias!