# Creación de guías
# Introducción
Parece algo de Perogrullo, pero las estanterías contienen los libros. Cada artículo, sea grande o pequeño, es un libro en la estantería de esta web. Estanterías, tenemos de momento tres, una para guías en español, en francés y otra para guías en inglés. Esperamos ampliar pronto con algunas guías en japonés.
El propósito de tener organizada la documentación en guías rápidas es **evitar los documentos largos y tediosos**, por eso cada documento se debe dividir en páginas, que tratarán un problema cada vez. Se hará una página nueva y se enganchará con la siguiente para poder leer de una manera cómoda y que no "atosigue" al lector de la guía.
En esta web la jerarquía de elementos es ESTANTERIA > LIBRO > CAPITULO > PAGINA. En la mayoría de los casos no utilizaremos capítulos, solo LIBROS y PÁGINAS, para simplificar la lectura de las guías, que deberían ser siempre cortas y concisas. Huimos de los textos llenos de apartados, subcapítulos y anexos. Para eso está otro tipo de documentación (Wiki) que ya tenemos. No lo olvides.
[**SIGUIENTE >**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/creando-un-libro)
# Creando un libro
Crear un libro, si tienes permisos, es sencillo, solo tienes que ir a la pantalla principal de la estantería y hacer click en "Nuevo libro:"
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603180964732.png)
Rellenar los datos que te piden. Presta especial atención a lo de subir una portada. Es importante que cada guía tenga una portada significativa, si es sobre alguna tecnología, que muestre el logo de dicha tecnología o algo relacionado. También tendrás que tener en cuenta el uso de TAGS, en este caso usamos LANG con valor ES para indicar que el articulo está en español:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/libro1.png)
Solo esto. Ya estás listo para el siguiente paso: ¡añadir páginas a tu libro!
[**< ANTERIOR**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/introduccion) [**SIGUIENTE >**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/pagina-nueva)
# Página nueva
Desde la vista principal del libro, podrás ver que la primera opción del menú de la derecha, permite crear una página:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/paginanueva.png)
Cuando creas una página, esto es lo que ves. Existe una barra de botones arriba para darle formato, para agregar imágenes y un sinfín de cosas más. Puedes copiar y pegar imágenes desde tu ordenador, arrastrar imágenes, hacer tablas, editar y otras muchas cosas. Ahora simplemente, conténtate con editar el contenido y asegurarte de que no sea demasiado largo.
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/edicionpagina.png)
Al terminar, darle a GUARDAR, el botón de arriba a la derecha:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603181476721.png)
**[< ANTERIOR](https://pandorafms.com/guides/public/books/creacion-de-guias/page/creando-un-libro)** [**SIGUIENTE >**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/enlace-a-siguiente-pagina)
# Enlace a siguiente página
La tecnología de momento no permite hacerlo de manera automática, asi que crearemos enlaces a mano. Para ello escribiremos el texto "SIGUIENTE >" y lo alinearemos a la derecha al final del documento, y lo enlazaremos manualmente a la siguiente página. Esto hará que leer una guía sea un proceso fácil de seguir, sin tener que ir al menú de la izquierda:
Para crear el enlace, seleccionaremos la palabra que hemos creado (SIGUIENTE >) y le daremos al botón de crear link:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/image-1603181644831.png)
Obtendremos la URL del capítulo al visualizarlo desde otra ventana del navegador y lo usaremos para construir en enlace:
Posteriormente podremos hacer lo mismo con el enlace para ir a la página anterior.
Aunque este proceso lo haremos rápidamente, puede ser que en otras ediciones de página nos lleve más tiempo. BookStack guarda automáticamente *y también permite que guardemos un borrador en cualquier momento que necesitemos.*
*[](https://pandorafms.com/guides/public/uploads/images/gallery/2021-04/bookstack-save-draft.png)*
Finalmente, para guardar la edición, por favor utilizad la opción **Set Changelog** el cual permite colocar un comentario en la edición: escribir y *presionar la tecla* Intro *o* Enter y el cambio será almacenado.
[](https://pandorafms.com/guides/public/uploads/images/gallery/2021-04/bookstack-set-changelog.png)
Al consultar las ediciones queda de esta manera:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2021-04/bookstack-page-revisions.png)
**[< ANTERIOR ](https://pandorafms.com/guides/public/books/creacion-de-guias/page/pagina-nueva) [ SIGUIENTE >](https://pandorafms.com/guides/public/books/creacion-de-guias/page/consejos-generales)**
# 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*:
[](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":
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/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](https://pandorafms.com/guides/public/books/creacion-de-guias/page/enlace-a-siguiente-pagina).
#### 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:
*¿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:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/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:
[](https://pandorafms.com/guides/public/uploads/images/gallery/2020-10/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** ](https://pandorafms.com/guides/public/books/creacion-de-guias/page/enlace-a-siguiente-pagina) [**SIGUIENTE >**](https://pandorafms.com/guides/public/books/creacion-de-guias/page/recomendaciones-generales-y-estilo)
# Recomendaciones generales y estilo
La documentación técnica tiene un estilo de redacción diferente al periodismo, a la literatura de ensayo o a la escritura comercial (*copywritting*). Debe ser aséptica, neutra, eficaz y rápida. Para ello hay que ser lo más objetivo posible, evitar cualquier figura literaria, adorno de estilo y simplificar al máximo las expresiones, las estructuras del lenguaje. Para ello, se deben emplear frases cortas con tiempos verbales simples.
Como desconocemos a la persona que va a leer el texto, asumimos como regla general dos cosas, en todo momento.
1. Contextualizar al lector para que entienda de lo que hablamos, ya que no conocemos sus conocimientos.
2. No des nada por supuesto. El lector no tiene porqué saber cosas que nosotros damos por sabidas a la hora de explicar lo que estamos explicando.
Obviamente no se trata de enseñar al lector a sumar si estamos hablando de operaciones aritméticas complejas en el manual, pero si introducimos por primera vez conceptos como “nodo” o “SNMP” conviene asumir que el lector no sabe lo que significan, y la primera vez, hacer el esfuerzo de hacer una pequeña introducción a dichos conceptos.
**[< ANTERIOR](https://pandorafms.com/guides/public/books/creacion-de-guias/page/consejos-generales)**