breaks: false repo: https://mutabit.com/repos.fossil/documentaton/ level: beginner language: es sync: - https://docutopia.tupale.co/inkit:r3p:codimd - repo://es/capitulos/codimd.md

CodiMD: Escritura síncrona colectiva

En ocasiones queremos escribir a muchas manos. Puede ser que estemos en un taller y queramos tomar notas de manera colectiva. O bien estamos trabajando en un documento y quisiéramos reunirnos con coautores para arrojar ideas, escribir subsecciones o realizar correcciones. Para ello se han creado varias plataformas que con sólo un enlace web permiten iniciar la colaboración con todos los que tengan dicho enlace (suponiendo que tienen los permisos para ello). Debido a que cuando los coautores se encuentran a través de la web, pueden escribir al mismo tiempo y ver los cambios de otros, se dice que dichas plataformas trabajan en "tiempo real".

Por otro lado, a veces queremos facilitar los procesos de escritura desde múltiples dispositivos y pantallas (incluso las pequeñas de dispositivos móviles) y en este caso un lenguaje de etiquetamiento ligero es una mejor opción que un editor pesado como Google Docs u Office 360, pues permite concentrarse en el contenido y explicitar ágilmente la estructura con unas marcas sencillas. Puedes ver más sobre dichas motivaciones en nuestro texto introductorio sobre documentación aǵil.

CodiMD es una de tales plataformas para escritura colectiva en tiempo real, usando lenguages de etiquetamiento ligeros. Emplea un supraconjunto de Markdown, llamado CommonMark, que permite varias características necesarias en la edición de textos profesionales, como tablas, avisos (advertencias, consejos), imágenes, videos, notas a pie de página, entre otros. El documento que estás leyendo acá, por ejemplo fue escrito colectivamente empleando CodiMD.

Una de sus principales ventajas es que permite ver en simultáneo el código de lo que se escribe, como su previsualización, empleando para ello un sistema de páneles dobles simultáneos, así las personas pueden enfocarse sólo en la escritura, sólo en la lectura o en ambas.

Registro

El registro se puede hacer de dos formas, usando herramientas externas como GitHub, Google o Twitter o a través del registro por correo electrónico.

::: danger Revisar definición de las capturas :::

Luego de elegir una de estas opciones y validar el registro, es posible editar los documentos.

A diferencia de los Pads que se han venido utizando en los Data Rodas anteriores, en donde los documentos quedan públicos y abiertos a la edición de cualquier persona, en esta oportunidad se ponen en debate la limitacion en la edición de contenidos por terceras personas agenas al proyecto, con el fin de garantizar la privacidad y seguridad de la documentación producida. <!-- Lecciones de Montenegro. Algunos asistentes, según cuenta Offray, pusieron en consideración esta práctica justamente por la seguridad de la información que se genera de manera colaborativa. -->

:::success Regístrate en un proveedor de CodiMD como Docutopia o Heroku. :::

Crear pads

Escencialmente hay dos formas:

• Desde la portada de la instancia de CodiMD.

A través del botón azul en la esquina superior derecha de la pantalla, como se vé a continuación

{width=40%}

• A través de un enlace al nuevo documento.

  Durante el proceso de documentación colaborativa podemos incluir enlaces en los documetos de manera fluida, para los efectos de esta comunidad se van a relacionar contenidos siguiedo la estructura de enlaces de Markdown, con la siguiente convención:

  • se incluirá entre corchetes cuadrados el texto que va a contener el enlace, por ejemplo [texto].
  • Luego se incluirá el complemento de la URL del recurso, determinando la ruta de orignen del nuevo documento entre paréntesis "()".
  • El contenido entre paréntesis incluirá la ruta a partir del "./" para referirse al servidor que estamos usando, seguido de dos puntos (:) para diferenciar las "carpetas" o secciones del tema relacionadas con el contenido.

  • Finalmente, el resultado será algo como texto. Para referenciarlo al ejercicio de esta sesión sería algo como

    [texto](./tema:subtema:pad)
    

    En donde el texto del enlace "texto" refiere al lugar usando en el servidor de Docutopia relacionado con los contenidos de la tema y el subtema.

:::success Crea un pad en el proveedor en el que te registraste en la actividad previa. :::

Descargar pads

Una vez hemos creado nuestros documentos en línea, puede ser necesario descargarlos para tener una copia de respaldo de los mismos o trabajarlos fuera de línea. Acá veremos tres métodos para ello.

Desde el navegador

A través de la vista de escritura, podemos acceder al menú desde el botón en el margen superior derecho, donde se muestran las diferentes opciones de descarga del documento: Markdown, HTML, HTML Raw y PDF.

{width=60%}

:::success Descarga un pad desde el navegador. :::

Con wget

:::info Suponemos que para esta parte tienes instalada la terminal o consola, o línea de comandos, que sabes cómo abrirla y los elementos básicos de escribir y ejecutar comandos en ella. También que tienes instalados los programas que se usan habitualmente en ella, como wget.

Usaremos los términos terminal, consola o línea de comandos de manera intercambiable. :::

Otra de las maneras de descargar un documento es emplear la terminal. La ventaja de este procedimiento es que podemos agilizar muchas descargas con sólo repetir un comando de una línea, lo cual abre a su vez la posibilidad de automatizarlo.

Para descargar este documento, abre la terminal y escribe:

  wget -O codimd.md https://docutopia.tupale.co/inkit:r3p:codimd/download

Con esto hemos creado un archivo llamado codi.md, en el disco duro, con los contenidos guardados en la dirección del pad cuyo enlace es inkit:r3p:codimd y está hospedado dentro del servidor https://docutopia.tupale.co. Si queremos descargar otros pads con otros enlaces, creados en otro servidor, o guardarlos con otros nombres de archivo, deberemos cambiar el comando previo respectivamente.

:::success Descarga un pad utilizando wget. :::

Con Pharo

Pharo es la plataforma sobre la cual está hecho Grafoscopio, que a su vez sirve para integrar y automatizar mucho del trabajo sobre investigación y publicación reproducible y remezclable, así que veremos cómo emplearla en las actividades de este texto de maneras progresivamente más elaboradas.

(pista: elegant code).