Guía de uso de Bookstack

• Comenzar a usar la documentación
• Cómo crear una cuenta en Bookstack
• Cómo navegar dentro de la documentación
• Crear una página
• Crear un libro
• Cómo dejar un comentario
• Glosario

Comenzar a usar la documentación

Documentar es tan fácil como explicar una receta a otra persona. Lo simple o complicado que sea, depende las herramientas que uses y lo familiarizado que estés con ellas. Si quieres grabar un vídeo y no sabes usar una videocámara o teléfono, puede ser un poco enredado. De igual forma, si quieres documentar en línea, pero no conoces el software, puedes enredarte innecesariamente. 

Por eso hemos creado esta guía para que conozcas los conceptos básicos e instrucciones esenciales para documentar en línea usando el software Bookstack.

Bookstack es una biblioteca digital

Bookstack usa la idea biblioteca para organizar la documentación, por lo que cada tema se documenta en libros, que pueden contener capítulos y páginas con texto, imágenes, etc. Y a su vez, estos libros pueden organizarse dentro de estantes. Esta idea hace muy fácil su uso y ayuda a mantener la documentación ordenada.

Supongamos que quisiéramos documentar recetas de comida, nuestra documentación podría organizarse de la siguiente forma en Bookstack:

• Estante: Recetas familiares
  • 📘 Libro: Recetas de la Abuela María
    • Capítulo: Postres
    • Capítulo: Atoles
  • 📘 Libro: Recetas de la Familia Caal 
    • Capítulo: Recados tradicionales
    • Capítulo: Tamales
• Estante: Recetas del mundo
  • 📘 Libro: Recetas de México
  • 📘 Libro: Recetas de El Salvador

Muy simple de entender, ¿cierto?

Documentar es un ejercicio de creatividad

Toda documentación surge de una página en blanco. Es algo que queremos contar, pero a veces no sabemos que forma darle, por lo que toma tiempo y esfuerzo. No te frustres si no consigues documentar tan rápido como quisieras, pero asegúrate de avanzar poco a poco. Por eso decimos que es un ejercicio de creatividad, porque debes ejercitarte para poder hacerlo cada vez mejor.

La mejor forma de comenzar a documentar es imaginar que estás explicándole algo a otra persona, o a ti misma, pero unos dos años en el futuro:

• ¿Qué necesita saber para hacer eso que quieres explicarle?
• ¿Cómo puedes explicárselo con palabras que le sean familiares?
• ¿Cómo puedo explicárselo de forma interesante para que no se aburra?
• En dos años, cuando regrese a realizar este procedimiento, ¿Qué sería importante recordar? 

También es un ejercicio de colaboración

Uno de los objetivos más importantes de la documentación es compartir información. Es expresar algo que nosotros sabemos, pero que necesitamos que otras personas sepan.

Documentar es hacer visible nuestro conocimiento para que otros aprendan, y a su vez nos ayuden a realizar nuestro trabajo. Es un ejercicio permanente de colaboración. Siempre tendrás conocimientos nuevos que compartir y aprender, y cuanto más compartas, más aprenderás. 

Así que no pienses en la documentación como algo estático y aburrido, sino como algo dinámico que tú y otras personas harán crecer, y que mientras lo hacen podrán compartir, y todo eso es un buen ejercicio de colaboración.

Y un ejercicio de respeto

Como todo trabajo colaborativo, debe comenzar con la creación de acuerdos para trabajar, de lineamientos básicos, de calidad y altas dosis de empatía, de pensar en los demás y como los demás.

Es válido pensar que otras personas desconocen alguna las cosas que estás documentando, precisamente para eso las estás documentando, pero no asumas que no saben nada o que saben menos, porque posiblemente saben muchas otras cosas que tú desconoces, así que muestra respeto al compartir información y dar indicaciones.

La mejor forma de documentar es hacerlo en función de las necesidades de los demás. Pregúntales qué necesitan saber y de qué forma les sirve más, e intenta satisfacer esas necesidades. De esa forma, tu esfuerzo será más eficiente y tendrá un mayor impacto. 

¡Comencemos!

Cómo crear una cuenta en Bookstack

Pasos para crear cuenta

1. Visitar la página https://memoria.meegt.org
2. Haz clic en el botón "Registrarse", en la parte superior derecha de la página.
3. Completa el formulario con tus datos personales: Nombre, correo electrónico y contraseña.
4. Al terminar, recibirás un mensaje en tu correo en el que debes presionar el botón que dice "Confirmar correo electrónico". Al hacer esa confirmación, se completará el proceso y podrás iniciar sesión. 

Luego de iniciar sesión, tendras permisos limitados hasta que una administradora te asigné los permisos adecuados para los espacios en los que colaboraras.

Con permisos limitados, aún podras escribir comentarios, guardar páginas en tus favoritos o crear páginas en algunos libros.

Preguntas frecuentes

¿Quién puede crear una cuenta?

Cualquier miembro activo del MEE, incluyendo al enlace principal u otras personas de la organización. 

¿La cuenta es aprobada automáticamente?

Sí, puedes crear tu cuenta y al confirmar tu correo electrónico estará aprobada automáticamente. Pero ten en cuenta que tendrás permisos de edición y visualización limitados, por lo que aún no verás todo el contenido hasta que una administradora te amplié los permisos correspondientes para poder colaborar.

Cómo navegar dentro de la documentación

El software para usar la documentación se llama Bookstack, así que cuando hagamos referencia al contenido hablaremos de "documentación" y cuando hablemos del software usaremos "Bookstack".

¿Cómo está organizada la documentación en Bookstack?

Bookstack se organiza en 4 tipos de contenido:

1. Estante: sirve para agrupar y organizar libros de documentación, y puede contener uno o muchos libros. A diferencia de los libros físicos, un libro puede estar en más de un estante a la vez. 
2. Libro: un libro agrupa las páginas de documentación y puede tener capítulos.
3. Capítulos: sirven para agrupar páginas de contenido relacionado dentro de un libro. Por ejemplo, si tuviéramos un libro de "Recetas de cocina", un capítulo podría ser "Postres" y otro "Entradas", para separar las diferentes recetas. 
4. Páginas: son documentos de texto, donde finalmente se encuentra el contenido de la documentación. Pueden tener formato, imágenes, vídeos, tablas y otros elementos gráficos para hacer la documentación más completa.

Cómo encontrar documentación

Hay varias formas de encontrar documentación en Bookstack, las principales son:

1. Usar el buscador, que se encuentra en la parte de arriba de la página. Es la opción más útil si sabes exactamente lo que estás buscando, pero no sabes en qué estante o libro se encuentra.

2. Navegar en la sección de Estantes o Libros, si quieres explorar la documentación por temas y descubrir qué contenido existe. Puedes acceder a la sección de  Estantes o Libros usando los enlaces en la parte superior de la página.

3. Usar la página principal de la documentación, que te mostrará las páginas vistas recientemente, las páginas modificadas recientemente, tus páginas o libros favoritos y todo el contenido creado recientemente.

Puedes acceder a la página principal haciendo clic en el logotipo del MEE en la parte superior izquierda de la página.

Crear una página

1. Para crear una página primero hay que tener un libro o capítulo creado.
   1. Si ya está creado, ve hacia esa página del libro o capítulo.
   2. Si no está creado, primero crea el libro.
2. Cuando estés en el libro o capítulo, haz clic en la opción a un lado de la pantalla que dice: Nueva página.
3. Esa opción, te llevará a una página vacía en la que puedes colocar el título de la página y comenzar a escribir el contenido.
   

Vista en teléfono	Vista en escritorio

Todo lo que escribas en la página se guardará automáticamente como un borrador.

Al finalizar de editar el contenido de la página, presiona la opción que dice Guardar página para guardar todos tus cambios.

Opciones adicionales

Las páginas tienen varias características útiles que puedes usar para mejorar el contenido, como las etiquetas, los archivos adjuntos o el uso de plantillas.

Agregar archivos adjuntos a la página

En la barra de herramientas del lado derecho, puedes abrir el panel de Archivos Adjuntos presionando el icono con un clip.

En el panel de Adjuntos encontrarás dos botones, para subir un archivo desde tu computadora o para adjuntar un enlace de Internet. También puedes arrastrar un archivo desde el explorador de archivos de tu computadora y soltándolo sobre la sección debajo de los botones.

Luego de subir un archivo adjunto, puedes agregar un enlace a la página icono de clip, a un lado del título del archivo.

También puedes reemplazarlo por otro documento usando el icono del lápiz, o eliminarlo usando la equis roja.

Agregar etiquetas de contenido a la página

Para agregar etiquetas, puedes usar el botón a un lado de la página con forma de etiqueta

Las etiquetas sirven para agregar información adicional a una página, y que sea más fácil de encontrar o de agrupar. Por ejemplo, puedes crear etiquetas relacionadas con la mesa de trabajo, a la categoría, o al tipo de contenido que tiene la página.

Al terminar de agregar las etiquetas, puedes cerrar el panel lateral usando el icono de la flecha. Y las etiquetas se guardarán al Guardar la página.

Usar plantillas para pre-cargar contenido

Las plantillas son páginas ya creadas que pueden copiarse, para no comenzar una página desde cero.

Al hacer clic en el título de la plantilla se reemplazará el contenido existente de la página. Así que si ya escribiste contenido, lo mejor es que revises las otras opciones de agregar plantilla que te presentamos abajo.

Las plantillas se encuentran en la sección de plantillas, que se muestra usando el botón de un cuadrado con dos líneas en medio, del lado derecho de la pantalla

Si la página está en blanco, se puede presionar el título de la plantilla para pre-llenar el contenido.
Si la página no está en blanco y se quiere agregar la plantilla hasta arriba del contenido, se debe presionar el botón a un lado del título con flecha hacia arriba.
Si la página no está en blanco y se quiere agregar la plantilla hasta abajo del contenido, se debe presionar el botón a un lado del título con flecha hacia arriba.
Si la página no está en blanco y se quiere agregar en otro lugar de la página, por ejemplo en medio, se puede arrastrar el título de la plantilla hacía y soltarla al lugar en donde se quiere agregar.

Una vez se agregó una plantilla al contenido, se puede editar, como cualquier otro contenido. Las plantillas solo funcionan como una copia de contenido que se pueda utilizar más de una vez.

Visita la página Crear una plantilla para aprender a crear tus propias plantillas.

Crear un libro

Crear libros es una tarea común al comenzar a documentar, pero con el tiempo es una tarea que se realiza cada vez menos. Así que es posible que no tengas que crear libros al iniciar, sin embargo, si necesitas crear uno es bastante simple de hacer siguiendo los siguientes pasos.

• Ve a la sección de Estantes e ingresa la Estante en donde quieres crear el libro.
• En el panel de herramientas encontrarás la opción de "Nuevo libro" (ver imagen abajo)

• Completa los datos básicos y luego presiona el botón de Guardar libro. Y listo, habrás creado un nuevo libro.
  

Información avanzada de nuevo libro

Además de la información básica del libro, también puedes agregar información adicional al libro, como imagen de portada, etiquetas o plantilla a usar por defecto al crear nuevas páginas.

Para agregar una Imagen de portada, presiona la sección con ese texto y luego el botón de Seleccionar imagen, para cargar una imagen existente en tu computadora. Los formatos soportados son JPG o PNG.

La sección de Etiquetas de libro sirve para agregar metadatos al libro, que puedan ser de utilidad para búsquedas o incluir otro tipo de información, como palabras clave. En el ejemplo de abajo, se incluye el metadato "Mesa" que indica la mesa de trabajo a la que pertenece el libro.

Y, finalmente, la sección de Plantilla de página por defecto, que permite elegir una plantilla para que sea usada siempre que se cree una nueva página en ese libro. No es obligatorio seleccionar una plantilla, pero puede ser un recurso muy útil para acelerar el trabajo de documentación. 

Si aún no has creado una plantilla, no te preocupes, puedes guardar el libro y editar la plantilla que deseas usar luego. 

 

Cómo dejar un comentario

Todas las páginas de la documentación tienen un área de comentarios, en la parte de abajo del contenido. Puedes dejar un comentario para ampliar información, dar sugerencias, realizar preguntas o expresar una opinión.

Agregar comentario

Para dejar un comentario, visita una página (puedes usar está para practicar) y al final de la página presiona el botón Añadir comentario.

Al terminar de escribir tu comentario, presiona el botón de guardar y listo.

Editar o borrar comentarios

Luego de publicar un comentario, puedes editarlo o eliminarlo usando los botones en la parte superior del comentario.

Glosario

Termino	Definición
Bookstack	Nombre del software usado para gestionar las páginas de documentación. Se considera software libre, lo que significa que la licencia de uso es gratuita, se puede modificar y se puede compartir con cualquier persona que lo desee usar.
Borrador	Página de documentación que ha sido guardada automáticamente por el software, pero que aún no se ha guardado por la persona editora. Al guardarse, la página deja de considerarse borrador y se convierte en una página.
MEE	Abreviatura de Movimiento Ecológico Estudiantil
Documentación	Es el nombre que recibe todo el contenido creado para ser consultado posteriormente, con fines de registro, informativos, didácticos, etc.   La documentación puede almacenarse de múltiples formas, como cuadernos, documentos digitales, vídeos, etc. En este caso, la documentación es digital y es gestionada con el software Bookstack.
Log de cambios	Es un registro de cambios realizados en una página. Puede mostrar qué persona y a qué hora editó una página.
Plantilla	Es una página de contenido, que se crea como cualquier otra, sin embargo, tiene la característica especial de que puede ser copiada para usar en documentos nuevos, como un molde. Las plantillas sirven para ahorrar tiempo al crear contenido que es similar a otro contenido previo.