# 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<span style="text-decoration: underline;"> lo dividiremos en partes, nunca será un solo bloque</span>. 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:

- - - <span style="font-weight: 400;">Por ejemplo,</span><span style="font-weight: 400; color: #ff0000;"> ASÍ NO:</span>
            
              
            *<span style="font-weight: 400;">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.</span>*
            
              
            <span style="font-weight: 400; color: #008000;">ASÍ SÍ:</span>
            
              
            *<span style="font-weight: 400;">Ingredientes:</span>*
            
            
            - *<span style="font-weight: 400;">Un vaso de lentejas.</span>*
            
            
            - *<span style="font-weight: 400;">100gr de chorizo cortado en rodajas</span>*
            
            
            - *<span style="font-weight: 400;">⅛ de cebolla en rodajas grandes.</span>*
            
            
            - *<span style="font-weight: 400;">Una cucharada pequeña de pimentón.</span>*
            
            
            - *<span style="font-weight: 400;">Una cucharada pequeña de sal.</span>*
            
            
            - *<span style="font-weight: 400;">Una cucharada pequeña de aceite antes de hervir.</span>*
            
              
            *<span style="font-weight: 400;">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.</span>*

#### <span style="font-weight: 400;">Formateo de comandos y pantallas.</span>

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

[![image-1603181991508.png](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/scaled-1680-/image-1603181991508.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603181991508.png)Por ejemplo:

```shell
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](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/scaled-1680-/image-1603182033546.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603182033546.png)

<p class="callout warning align-left">Una guía rápida debe ser rápida y precisa. No te enrolles (esto es un ejemplo de callout)</p>

#### Botones de navegación entre páginas

Los botones de navegación "**SIGUIENTE &gt;**" y "**&lt; 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 <span style="text-decoration: underline;">¡no olvides meterlos!</span> Puedes ver como se usan [en esta guía](https://pandorafms.com/guides/public/books/creacion-de-guias/page/enlace-a-siguiente-pagina).

#### Capturas de pantalla

Una captura debería estar <span style="text-decoration: underline;">siempre centrada</span> y <span style="text-decoration: underline;">siempre debería poder leerse lo que pone en su interior sin ampliar imagen o hacer click en ella</span>. **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](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/scaled-1680-/capturamala.png)*¿Puedes leer algo en ella?, por eso no vale para nada esta captura.*

Una imagen <span style="text-decoration: underline;">nunca debería verse más grande de lo que se ve en una pantalla normal</span>, 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, <span style="font-weight: 400;">habrá que indicarlo con un <span style="text-decoration: underline;">círculo rojo bien visible,</span> por ejemplo:</span>

[![image-1603321129838.png](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/scaled-1680-/image-1603321129838.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603321129838.png)

<span style="font-weight: 400;">Revisa que las capturas de pantalla que hayas puesto <span style="text-decoration: underline;">no contengan datos confidenciale</span>s.</span>

<span style="font-weight: 400;">La Shell o<span style="text-decoration: underline;"> los comandos se pondrán en texto</span> 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:</span>

<span style="font-weight: 400;">[![shellmal.png](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/scaled-1680-/shellmal.png)](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/shellmal.png)</span>

#### <span style="font-weight: 400;">Consejos breves de estilo</span>

**Menos siempre es más.**<span style="font-weight: 400;"> 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: </span>**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.

[**&lt; ANTERIOR** ](https://pandorafms.com/guides/public/books/creacion-de-guias/page/enlace-a-siguiente-pagina) [**SIGUIENTE &gt;**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/recomendaciones-generales-y-estilo)