Skip to main content

Consejos generales

Algunos consejos generales buenos para cualquier guía rápida.

Paso a paso

Utiliza las páginas para dividir el contenido al máximo. Intenta que no haya scroll vertical, y si lo hay que sea mínimo. Cuando hablemos de algo técnico que es complejo y que requiere una serie de pasos lo dividiremos en partes, nunca será un solo bloque. De esta forma, cuando el usuario intente realizarlo por su cuenta y falle en un paso, sabrá dónde se queda y no será tan confuso para él. Dentro de una página, lo dividiremos en pasos siempre que sea posible. Veamos un ejemplo:

      • Por ejemplo, ASÍ NO:


        Eche un vaso de lentejas, tres vasos de agua, algo de chorizo. Esperar 2 horas. También se puede echar cebolla. Algunas personas le echan aceite antes de hervir, otros después, un poco de pimentón también viene bien. El fuego conviene que no sea alto, y si lleva hora y media y está seco, echar un poco de agua y bajar el fuego.


        ASÍ SÍ:


        Ingredientes:

        • Un vaso de lentejas.
        • 100gr de chorizo cortado en rodajas
        • ⅛ de cebolla en rodajas grandes.
        • Una cucharada pequeña de pimentón.
        • Una cucharada pequeña de sal.
        • Una cucharada pequeña de aceite antes de hervir.

        Dejar a fuego medio durante dos horas. Verificar cada media hora, si se va quedando sin agua, añadir un poco y bajar el fuego.

Formateo de comandos y pantallas.

Separa todas las instrucciones de "ejecutar cosas" usando el formateo de code block:

image-1603181991508.pngPor ejemplo:

cd /
find -name "pandora.conf" -print
rm -Rf /etc/pandora

Utiliza el formateo de "callouts" para indicar puntos especiales en modo "atención", "cuidado":

image-1603182033546.png

Una guía rápida debe ser rápida y precisa. No te enrolles (esto es un ejemplo de callout)

Botones de navegación entre páginas

Los botones de navegación "SIGUIENTE >" y "< ANTERIOR" hay que hacerlos a mano, pero son muy útiles para el lector. puedes dejarlos para el final, cuando todo lo demás esté hecho, pero ¡no olvides meterlos! Puedes ver como se usan en esta guía.

Capturas de pantalla

Una captura debería estar siempre centrada y siempre debería poder leerse lo que pone en su interior sin ampliar imagen o hacer click en ella. De nada sirve meter capturas donde no se puede leer el contenido. No utilices capturas de pantalla completas, utiliza recortes de las mismas. Así mismo, queda igual de mal ver imágenes demasiado ampliadas. Veamos una captura mal usada:

capturamala.png¿Puedes leer algo en ella?, por eso no vale para nada esta captura.

Una imagen nunca debería verse más grande de lo que se ve en una pantalla normal, salvo que haya una razón expresa para ello. Además quedan horribles, lo mismo que si están deformadas respecto a su relación de aspecto original.

Si hay que hacer click en algún lugar, habrá que indicarlo con un círculo rojo  bien visible, por ejemplo:

image-1603321129838.png

Revisa que las capturas de pantalla que hayas puesto no contengan datos confidenciales.

La Shell o los comandos se pondrán en texto en formato codeblock, no con capturas de pantalla para que el usuario pueda “copiar / pegar” si lo necesita, de una imagen no se puede copiar/pegar. Esta captura por ejemplo no es útil:

shellmal.png

Consejos breves de estilo

Menos siempre es más. Cuanto más precisa sea la documentación, mejor. Si un texto que ocupa 200 palabras podemos dejarlo en 100 sin perder un ápice de significado, mejor. Se deben emplear: frases cortas, sin subordinadas y con vocabulario técnico, preciso, y aunque se repita, no será necesario utilizar sinónimos. 

Documentar no consiste en demostrar lo mucho que se sabe, a veces habrá que escoger qué contar para ir al grano y no perdernos con demasiadas explicaciones. Las guías rápidas tienen un propósito principal, realizar una tarea, y quizás uno secundario, aprender. Nunca hay que sacrificar el objetivo principal ni perderlo de vista.

 

< ANTERIOR   SIGUIENTE >

Back to top