Redacción colaborativa en Manubot

Redacción colaborativa en Manubot

Hace una semana llegó a mis manos un artículo de Nature.com sobre redacción colaborativa mediante un software llamado Manubot . El artículo explica la posibilidad de redactar de forma abierta manuscritos científicos. La idea central es implementar un sistema de control de versiones (Git) online (GitHub) para organizar la redacción de documentos. Este método propone un cambio de paradigma a la forma habitual de trabajar de un investigador, ya que el sistema permite visualizar en todo momento el avance del documento. Al trabajar en la plataforma GitHub es posible administrar la colaboración de un grupo de participantes numeroso. Además, existe la posibilidad de que cualquier persona con conocimientos del tema pueda proponer cambios al proyecto, en caso de ser aceptados dichos cambios, estos pueden ser integrados al manuscrito final.

En el artículo Open Collaborative with Manubot se muestra la descripción completa del software . Esta plataforma cuenta con una cantidad importante de características para el trabajo colaborativo, entre ellas destaca la posibilidad de citar documentos mediante el uso de los identificadores digitales (DOI – Digital object identifier), esto quiere decir que se evita la confusión por el uso de base de datos personales de cada miembro. En la Figura 1, podemos observar la comparación de características entre las distintas plataformas que permiten redactar documentos de forma colaborativa. Sin duda alguna, la propuesta que ofrece Manubot es excelente. Sin embargo, para poder utilizarla se requiere de habilidades básicas de programación.

Para trabajar en Manubot se requiere conocimientos básicos de programación: Git + GitHub + Markdown

Comparación de características de plataformas que permiten la redacción de documentos en forma colaborativa.
Figura 1. Comparación de características de plataformas que permiten la redacción de documentos en forma colaborativa.

El principio de funcionamiento de Manubot se muestra en la Figura 2. Se ingresa código mediante lenguaje Markdown y se obtiene como resultado un manuscrito en distintos formatos (.html, .pdf, .docx.) que son utilizados para someter a publicación en una revista científica.

Funcionamiento de Manubot explicado en su página web
Figura 2. Funcionamiento de Manubot explicado en su página web

Después de leer las bondades del sistema Manubot, me he aventurado a implementar (clonar) el sistema para producir mi propio manuscrito online. Ahora que he logrado instalarlo, quiero compartir la experiencia contigo. Pero, antes de iniciar debo advertir que no fue fácil configurar el sitio ya que primero tuve que aprender sobre el funcionamiento de la plataforma GitHub.com.


Metodología

Mi experiencia en la instalación de Manubot ha sido desde el sistema operativo macOS. Sin embargo, también es posible implementarlo desde sistemas operativos como Windows y Linux. A continuación presento de forma general la metodología que seguí para lograr generar el manuscrito.

  1. Crear usuario en GitHub: URL
  2. Instalar GitHub Desktop: URL
  3. Leer la documentación del repositorio RootStock que se encuentra en GitHub, este es el repositorio que vamos implementar: URL
  4. Observa el resultado (web dinámica) que tendremos antes de iniciar: URL
  5. En el archivo SETUP.md, se muestran las instrucciones para la instalación de Manubot.

Yo tardé un par de días en lograr instalar el sistema, por lo tanto quiero facilitarte este trabajo. Sigue la guía de instalación paso a paso. Al final sólo habrá que editar el manuscrito e invitar (retar) a tus colegas a trabajar con Manubot.


Guía de Instalación de Manubot

Antes de iniciar es necesario contar con una terminal-shell en nuestro sistema operativo e ir a la carpeta en la cual queremos instalar el proyecto. En mi caso, al instalar GitHub desktop se ha creado una carpeta en Documentos/GitHub. Es en este lugar donde iniciaremos el terminal. Nota: Mac y Linux cuentan por defecto con un terminal-shell mientras que en Windows se debe instalar (Git Bash o Windows Subsystem for Linux).

MAC-OS Terminal-shell en la cual se realiza la instalación

1. Personalizar configuración

Ejecutaremos los siguientes comandos en la terminal para personalizar la configuración. No olvides colocar tus datos, nombre de usuario y nombre del repositorio.

# GitHub usuario (cambia a tu nombre de usuario )
OWNER=jesuscapistran

# Nombre de repositorio (proyecto nuevo)
REPO=mymanuscript

2. Clonar repositorios

Al clonar el repositorio rootstock tendremos una carpeta con nombre mymanuscript dentro de la carpeta Documentos/GitHub. Además, ejecutamos las siguientes instrucciones para configurar los remotes.

# Clone manubot/rootstock
git clone --single-branch https://github.com/manubot/rootstock.git $REPO
cd $REPO

# Configure remotes
git remote add rootstock https://github.com/manubot/rootstock.git

# Option A: Set origin URL using its web address
git remote set-url origin https://github.com/$OWNER/$REPO.git
Clon del proyecto rootstock en carpeta mymanuscript

3. Crear repositorio en GitHub

En esta etapa crearemos un repositorio público nuevo en GitHub (https://github.com/new) con el nombre propuesto (REPO), en mi caso mymanuscript. Nota: En caso de querer un proyecto privado se debe pagar una cuota, esto se debe a que GitHub es una plataforma que promueve el código abierto.

Creación de un repositorio nuevo en GitHub.
Creación de un repositorio nuevo en GitHub.

4. Subir contenido

Una vez creado el repositorio procedemos a subir el contenido de mymanuscript al repositorio creado en GitHub con el siguiente comando:

git push --set-upstream origin master

5. Implementar GitHub actions

En este momento, el proyecto completo de Manubot ya se encuentra en nuestro repositorio de GitHub.com. Por lo tanto, ahora borraremos los siguientes archivos (travis.yml, appveyor.yml, install.sh ) para activar de forma automática la funcionalidad de GitHub Actions. Al utilizar GitHub Actions, se activará la compilación del código cada vez que se aprueben cambios en el manuscrito.

# remove Travis CI config
git rm .travis.yml

# remove AppVeyor config
git rm .appveyor.yml

# remove ci/install.sh if using neither Travis CI nor AppVeyor
git rm ci/install.sh

6. Actualizar README.md

Otro cambio necesario, es actualizar el archivo README.md del proyecto con nuestros datos de nombre usuario (OWNER) y repositorio (REPO). Usa el siguiente código en la terminal para hacerlo.

# Perform substitutions
sed "s/manubot\/rootstock/$OWNER\/$REPO/g" README.md > tmp && mv -f tmp README.md

sed "s/manubot\.github\.io\/rootstock/$OWNER\.github\.io\/$REPO/g" README.md > tmp && mv -f tmp README.md

7. Finalizar instalación de Manubot

Como hemos realizado dos cambios después de subir los archivos de Manubout, es importante actualizar nuestro repositorio en GitHub.com https://github.com/jesuscapistran/mymanuscript . Esto se logra al ejecutar los siguientes comandos.

git add --update

git commit --message "Brand repo to $OWNER/$REPO"

git push origin master

Una vez realizados los cambios podemos ir a la sección Actions de nuestro repositorio, aquí podremos ver que Manubot procede a ejecutar una acción continua (compilar el proyecto completo) para generar la nueva versión de nuestro manuscrito en forma de pagina web dinámica HTML o documento PDF.

Proceso de compilación del proyecto mediante GitHub Actions
Proceso de compilación del proyecto mediante GitHub Actions

8. Activar y configurar GitHub-Pages

Para mostrar el manuscrito en forma de página web dinámica, es necesario indicar a nuestro repositorio (mymanuscript) el lugar donde se encuentra el código fuente (contenido). En la sección de configuración de nuestro repositorio (https://github.com/jesuscapistran/mymanuscript/settings) iremos al apartado GitHub Pages e indicaremos que la fuente será proporcionada por la rama(Branch) llamada gh-pages. Observa la siguiente imagen.

Configuración del repositorio. Se anexa el branch gh-pages como fuente de la pagina web

Editar el manuscrito (Online)

Al haber actualizado el archivo README.md y guardar los cambios se obtendrán dos links personalizados que nos dirigen a nuestro manuscrito generado.

Para editar el manuscrito existen diversas formas (GitHub Desktop, GitHub.com y Git). Por motivos de prueba usaremos la versión online GitHub.com. El contenido del manuscrito lo encontraremos en la carpeta content de nuestro repositorio.

Contenido del proyecto mymanuscript. El contenido del manuscrito se encuentra en la carpeta content
Contenido del proyecto mymanuscript. El contenido del manuscrito se encuentra en la carpeta content

Como ejemplo editaremos el archivo metadata.yaml . Este archivo contiene nuestros datos personales. En mi caso, agregué el siguiente código donde expongo el título de un posible manuscrito, las palabras clave, etc.

---
title: "Buffer layer analysis in copper antimony sulfide solar cell: A SCAPS-1D numerical simulation"
keywords:
  - CAS
  - thin-film
  - solar cells
  - scaps-1d
lang: en-US
authors:
  - github: jesuscapistran
    name: Jesús Capistrán-Martínez
    initials: JCM
    orcid: 0000-0001-8555-5440
    twitter: capis
    email: capistran@gmail.com
    affiliations:
      - Renewable Energy Institute, National Autonomous University of Mexico - UNAM
    funders:
      - Grant XXXXXXXX

El potencial de Manubot se encuentra en el control de versiones. Al guardar los cambios realizados, GitHub le enviará al administrador una propuesta de cambios (commit). Es importante que los co-autores envíen la modificación mediante una nueva rama (branch) para generar una versión alterna del documento completo que incluya los cambios propuestos.

Proponer cambios al proyecto mediante una nueva rama (Branch)
Proponer cambios al proyecto mediante una nueva rama (Branch)

Al agregar un cambio del texto (o codigo) mediante una nueva rama ( jesuscapistran-patch-1) se le solicita al administrador de proyecto revisar y en su caso aceptar el cambio. Una vez aprobado, Manubot ejecutará una vez más la compilación del documento. Dando como resultado una actualización que todos podríamos ver online, ver pagina web.

Borrador del manuscrito (online)
Borrador del manuscrito (online) URL – https://jesuscapistran.github.io/mymanuscript/

En este punto ya cuentas con un sistema de colaboración, sólo queda editar el contenido. Para lograrlo se tienen que modificar los archivos 01.abstract y 02.delete-me.md. Puedes agregar secciones independiente creando un nuevo archivo, ejemplo 03.introduccion.md, 04.metodologia.md. Recuerda que la redacción se debe realizar mediante el lenguaje Markdown. Yo recomiendo primero editar online mediante la extensión web para Chrome que ofrece https://hackmd.io/. Si buscas algun editor de Markdown, aquí los puedes encontrar (https://www.markdownguide.org/tools/). Espero hayas tenido éxito, no olvides dejar tus comentarios, observaciones y recomendaciones. Hasta pronto.

¿Haz logrado implementar tu sistema Manubot?

Referencias

[1]
D.S. Himmelstein, V. Rubinetti, D.R. Slochower, D. Hu, V.S. Malladi, C.S. Greene, A. Gitter, Open collaborative writing with Manubot, PLOS Computational Biology. 15 (2019) e1007128. https://doi.org/10.1371/journal.pcbi.1007128.
[1]
J.M. Perkel, Synchronized editing: the future of collaborative writing, Nature. 580 (2020) 154–155. https://doi.org/10.1038/d41586-020-00916-6.

Leave a Reply