Un nuevo manual escrito en AsciiDoc

Parte 2

Esta es la segunda parte de mi informe de proyecto para el nuevo manual de Merlin Project. Intentaré dar una actualización más o menos breve sobre el proyecto cada viernes.

El proyecto

Antes de entrar en AsciiDoc, echemos un vistazo a mi proyecto.

El repositorio Git ha sido configurado
Las líneas están definidas y algunas de ellas están listadas aquí también.
Los prerrequisitos son conocidos hasta donde llegan.
Se ha creado un primer esquema que ahora se irá perfeccionando poco a poco.
Como imágenes utilizaré primero sólo capturas de pantalla rápidas, y luego las recrearé según sea necesario.
Se ha fijado un día de la semana para escribir.

El último punto en particular fue un verdadero desafío para mí, porque de alguna manera tengo que encontrar el tiempo para escribir. Si sólo me tomo cada minuto disponible, probablemente nunca terminaré. Necesito un bloque de tiempo fijo y eso es exactamente lo que he creado. A partir de ahora, el miércoles es mi día de escritura manual. Vamos a ver cuánto tiempo funciona ...

Por supuesto, hay un tablero Kanban. Perdón por el idioma inglés - hacemos mucha documentación interna en inglés.

Consejos de AsciiDoc

Dividir archivos

No creo el manual en un solo archivo, sino que prefiero dividirlo capítulo por capítulo. También almaceno las variables y atributos de mi manual en un archivo separado para poder construir los archivos individualmente o verlos en el navegador y utilizar todas las variables y atributos. Este archivo suele llamarse Atributos y para que siempre pueda encontrarlo rápidamente, se le pone un "_" y así aparece siempre al principio de la lista de archivos.

ifndef::_attributes[]
include::_attributes.de.adoc[]
endif::[]

Aquí pregunto si la variable _attributes ya está configurada.
Si no, se incluye el archivo.

De esta manera me aseguro de que el archivo de atributos no se cargue varias veces, ya que cada archivo comienza con estas líneas.

Mi rápida evolución

De momento sigo escribiendo el manual en solitario, pero todos los textos y soportes van a Git. Esto significa que mi inicio matutino de la escritura comienza en la terminal, o - dependiendo de lo que tengo a mano - el BBEdit Unix Worksheet, con un animado git pull. Luego abro el archivo del proyecto BBEdit (que está incluido en el repositorio, por supuesto) y veo todos los archivos incluidos en la lista de la izquierda.

Divido la pantalla más o menos por la mitad: Estoy escribiendo en la izquierda y tengo abierto Chrome en la derecha. En la ventana del navegador simplemente arrastro el icono del proxy del archivo editado. Gracias a la extensión Asciidoctor.js el navegador se actualiza con cada guardado en BBEdit.