Viviendo el futuro de la escritura técnica

Las increíbles aventuras y la última cadena de herramientas de Pro Git, 2da Edición

Hace casi exactamente seis años, Apress se me acercó para ayudarme con un libro que se estaba escribiendo, pero que se estaba retrasando, llamado Pro Git. Eventualmente, el autor original decidió no seguir escribiendo y reescribí el libro desde cero, finalmente publicado alrededor de agosto de 2009. Durante los primeros tres capítulos, escribí el libro en Word, enviando documentos a mi editor y obteniendo versiones de línea roja algún tiempo después.

Después de unos tres capítulos de esto, estaba a punto de darme por vencido cuando sugerí que pasáramos a hacer el libro en Markdown para la fase de redacción y edición técnica y luego volviéramos a Word solo para la edición de copias que se acordó. Una vez que se completó el libro, volví a mover todo el contenido a Markdown para poder publicarlo en línea en el sitio web que creé. Afortunadamente para mí, el autor original consiguió que Apress aceptara que Creative Commons también autorizara el trabajo.

Más de un año después, Apress también lanzó una versión Kindle del libro, aunque las personas habían producido versiones compatibles con Kindle a partir del contenido de código abierto casi tan pronto como se lanzó el libro.

Pro Git, segunda edición

Como el libro ha funcionado razonablemente bien, después de cuatro años de estar en prensa, Apress se me acercó para hacer otra edición del libro. En el transcurso de ese tiempo, mi empresa GitHub pasó de ser 4 personas trabajando en un sitio para unos miles de usuarios a una presencia en línea gigante que alberga millones de repositorios y emplea a más de 200 personas. La comunidad de GitHub no solo había cambiado tanto, sino que la herramienta también había tenido algunos cambios significativos. Estuve de acuerdo en que probablemente era hora de renovar el contenido.

Si bien ahora puede leer la segunda edición (así como la primera edición) en línea o descargarla en formato PDF, ePub o Mobi (Kindle) para leer en su dispositivo favorito, pensé que una historia interesante para compartir sería la diferencia en cómo esta versión fue producida desde la primera versión hace unos cinco años.

La escritura de Pro Git v2

En realidad, comencé a renovar Pro Git varias veces en los últimos años. En general, me interesaron los aspectos de la cadena de herramientas. En algún momento comencé un proyecto llamado Git Scribe, que estaba destinado a demostrar el tipo de cadena de herramientas que desearía poder haber usado para escribir Pro Git. La herramienta de escritura proporcionó una manera semi-fácil de instalar una cadena de herramientas que tomaría un libro de Asciidoc específicamente formateado y produciría buenos ebooks de HTML, PDF, ePub y Mobi. Aunque el proyecto ya murió y terminamos usando la plataforma Atlas de O'Reilly, el proyecto Scribe me llevó a Asciidoc en primer lugar.

Asciidoc

Así que cambié grandes porciones de Pro Git a Asciidoc. El problema con Markdown fue que era demasiado simple. No especificó cosas como el formato de tabla, referencias cruzadas, indexación, textos destacados, ejemplos de código fuente, etc. Todo lo que hace Asciidoc en un formato que es igual de fácil de escribir.

Así que moví todo, desde Markdown a Asciidoc, y noté que algunos editores también lo estaban haciendo. O'Reilly comenzó a permitir que se escriban libros en Asciidoc, ya que genera Docbook fácilmente y creo que los programadores pragmáticos habían estado utilizando un lenguaje de marcado simple durante un tiempo antes de eso.

Lo más importante para todo esto fue el ascenso de Asciidoctor. Cuando fui a rehacer mi sitio web de Git (git-scm.com) quise tomar las fuentes de la página de manual de Asciidoc para Git y hacer buenas versiones en línea de ellas y quería hacerlo con Ruby. Mi amigo y compañero de trabajo de GitHub Nick Hengeveld escribió un buen analizador y formateador para Asciidoc para ayudarme a hacer esto. Finalmente, algunos otros GitHubbers (Ryan Waldron y Jeremy McAnally) se unieron y convirtieron Asciidoc.rb en Asciidoctor, que finalmente fue asumido por el increíble Dan Allen, quien llevó el proyecto a un nivel completamente nuevo.

Ahora que Asciidoctor está cerca, puedo hacer cosas verdaderamente sorprendentes con mi libro original de Asciidoc que antes no eran tan simples.

GitHub

Uno de los mayores cambios en el flujo de trabajo de escritura fue que GitHub está mucho mejor ahora que antes. Ahora teníamos Peticiones de extracción para revisar y comentar, emitir hitos para la planificación de capítulos, diffs en prosa para una revisión más sencilla y verificación al azar, y el editor de texto de Atom para la escritura y la vista previa de Asciidoc.

El flujo de trabajo que tenemos que usar es uno que todos los que alguna vez escribieron un libro técnico, especialmente con un coautor, probablemente estarán locamente celosos.

Escribimos todo lo que queríamos hacer, sumamos todos los puntos principales como problemas relacionados con los hitos de cada capítulo y luego cada uno de nosotros decidimos qué íbamos a hacer y empezamos a escribir. Podríamos hacer una rama para la unidad de trabajo que estábamos haciendo (normalmente un capítulo) y comenzar a escribir y enviar a la sucursal de GitHub. Hablamos en Slack y recibimos actualizaciones instantáneas cada vez que uno de nosotros impulsaba algún cambio. Abrimos una Solicitud de extracción casi de inmediato, generalmente con una lista de verificación de las cosas que queríamos completar antes de fusionar para poder saber cuál era el estado de cada rama (por ejemplo ).

Cuando una rama funcionaba mucho, podíamos fusionar la rama principal en ella para mantenerla actualizada y asegurarnos de que los conflictos nunca fueran un gran problema, incluso a través de cambios estructurales masivos como dividir capítulos en múltiples archivos.

La revisión se realizó a través de las Solicitudes de extracción: podíamos dejar comentarios en cualquier línea de texto introducido y tener una conversación allí o en un chat al respecto.

Pude instalar el complemento de vista previa Asciidoc Atom y obtener vistas renderizadas en vivo del texto que estaba escribiendo mientras escribía, incluidas sugerencias sobre lo que agregué, modifiqué o eliminé, en qué rama estaba, combiné herramientas de ayuda para conflictos. , modo zen, etc. Era un entorno de escritura increíble.

No solo esto, sino que hicimos la mayor parte de esta colaboración mientras se separaban 9 zonas horarias y nuestro editor podía consultar en cualquier momento la página de hitos para ver cuál era nuestro progreso a través del libro.

Si has escrito un libro técnico y no lo has hecho en Asciidoc en el GitHub moderno, has hecho diez veces más trabajo del que necesitabas.

Atlas

No solo fue más fácil escribir y colaborar en el libro que en la primera edición, pero ver cómo sería sería infinitamente más fácil.

El sistema de construcción O'Reilly Atlas. Apunte y haga clic para obtener hermosos libros electrónicos en minutos.

Gracias en parte a las conversaciones que tuve con Tim O'Reilly, Laura Baldwin y otros en O'Reilly Media hace unos años acerca de cuánto mejor podría ser esta cadena de herramientas, fui invitado a probar la plataforma que estaban desarrollando para que todo sea más fácil. . Todos estuvimos de acuerdo en lo grandioso que sería pasar de escribir en Asciidoc a 'git push' a PDF. Terminaron realmente construyéndolo y afortunadamente me dejaron probarlo.

Puede verme siendo bastante activo en su foro durante varios meses y cada vez que mencioné algo lo arreglaron en cuestión de días o incluso horas. No solo eso, sino que las compilaciones produjeron resultados tan bellos que, para las reseñas de los capítulos, terminé construyendo un PDF, descargándolo y leyéndolo en Vista previa mientras tomaba notas y cambiaba la fuente de Asciidoc.

Afortunadamente, también tienen una API para el servicio y puedes construir diferentes ramas por separado. Esto significa que pude escribir un servicio que escucha los ganchos post-recepción en el repositorio Pro Git, retira los cambios, los empuja a Atlas y automáticamente inicia una compilación. A continuación, realiza una encuesta para ver cuándo terminan todas las construcciones y las mueve a mi propio contenedor AWS S3 y actualiza el nuevo sitio web progit.org y el contenido y los enlaces del sitio web de git-scm.com.

No solo eso, sino que puedo hacerlo por cada idioma en el que se traduzca Pro Git. Esto significa que en el futuro cercano, si va al sitio web de Pro Git o al sitio web git-scm.com , puede descargar ebooks de nivel profesional en cualquier formato de la última versión de Pro Git minutos después de la última errata unir. En cualquier idioma. Con cero trabajo de mi parte o de los encargados del lenguaje después de presionar el botón 'fusionar'.

Básicamente, ahora tengo la configuración de producción y distribución de libros electrónicos multilingüe más simple y sofisticada del planeta.

Fuente abierta

Otra diferencia interesante entre la primera y la segunda ediciones es que, dado que no quería pasar de nuevo por el proceso Markdown to Word to Markdown, acordamos que podía escribir el libro en su totalidad y luego "tirarlo al otro lado de la pared" para Presiona quién haría la conversión de Word y copia de edición y luego envíanos los cambios. Esto significa que Ben y yo pudimos abrir la fuente del libro mucho antes en el proceso de lo que era capaz antes.

El libro está disponible en línea en su totalidad, incluso en todos los formatos de libros electrónicos, pero aún faltan meses para que se imprima. En este momento, estamos seguros de que obtendremos una tonelada de ediciones de copias pequeñas y correcciones técnicas (ya tenemos un puñado en las primeras 24 horas) y podremos unirlas antes de que Apress imprima. Esto significa que podemos encontrar y corregir erratas antes de imprimir el libro, lo cual es bastante sorprendente.

De hecho, debatimos la posibilidad de escribir todo el libro al aire libre o esperar hasta que estuviera completo antes de volver a abrirlo. Al final, optamos por lo último, aunque todavía no estoy seguro de que el primero no hubiera sido la mejor opción. Sentimos que podría ser una gran molestia lidiar con las opiniones de toda la comunidad durante todo el proceso y que preferimos tener el contenido un poco más fundamental, pero puede haber sido interesante haber tomado la otra ruta. Quizás la próxima vez.

Traducciones

Lo último que es dramáticamente diferente esta vez es el manejo de las traducciones del trabajo. Cuando abro la primera edición, no recuerdo haber pensado en traducciones. No recuerdo haber obtenido mi primer trabajo traducido, pero tuvo que haber sido bastante rápido después de que lo lancé porque reestructuré los directorios para poner todo en un directorio 'en' poco después del lanzamiento.

En los cinco años transcurridos desde la publicación del libro, se tradujo por completo a al menos 10 idiomas ( Deutsch, ?? ??, ? ? ??, Français, ???, Nederlands, ???????, ???, Português y ?eština ) y parcialmente se tradujo en probablemente otro 20. Desde que decidí almacenarlos en subdirectorios del repositorio principal y tomé Pull Requests para ellos, eso significaba que alguien que tenía acceso de escritura al repositorio tenía que fusionarlos. Lo que significaba que básicamente tenía que fusionar todo, aunque no puedo leer casi ninguno de estos idiomas. Finalmente, después de unos años, me puse muy mal para seguir con las solicitudes de extracción y el increíble Jean-Noël Ávila asumió el control y ha logrado las traducciones (e incluso la errata en inglés) desde entonces.

Esta vez, sin embargo, podemos aprender de los problemas que hemos tenido anteriormente y tratar de hacerlo más fácil para todos. Esta vez estamos haciendo que cada traducción sea un repositorio por separado dentro de la organización de programación y agreguemos mantenedores específicos de cada idioma. Esto significa que puede abrir un problema en la versión ZH en mandarín y no hacernos confundir por completo. Si los mantenedores dejan de responder y alguien más está interesado, podemos agregarlos como un nuevo mantenedor.

Gracias a Atlas, cada traducción también tendrá su propio proceso de compilación automatizado en lugar de hacer que todos ejecuten sus propias compilaciones localmente, como ha sido el caso hasta ahora.

En resumen

Creo que este proceso es al menos el futuro a corto y mediano plazo de la publicación técnica. Escribiendo su libro en un formato más simple como Asciidoc en GitHub, colaborando fácilmente con sus editores y coautores, abriendo el contenido, abrazando una comunidad robusta de traducción y autopublicación con herramientas como Asciidoc o Atlas.

También creo que todo esto tiene implicaciones muy serias e interesantes para la industria editorial en general, sobre lo que escribiré en profundidad en una publicación futura.

Hacker Noon es cómo los hackers comienzan sus tardes. Somos parte de la familia @AMI . Ahora estamos aceptando presentaciones y estamos felices de conversar sobre oportunidades de publicidad y patrocinio .

Si disfrutaste esta historia, te recomendamos que leas nuestras últimas historias tecnológicas e historias tecnológicas de tendencia . Hasta la próxima, ¡no des por sentado las realidades del mundo!

Texto original em inglês.