**Documentaton: técnicas y herramientas ágiles y resilientes para escribir y publicar juntos**
_por_ **La comunidad de Grafoscopio**
!!! WARNING
**En construcción**.
Por favor, suscríbete a nuestro RSS (arriba) y visita este sitio con frecuencia.
Cuando este letrero desaparezca o cambie, el documento que acá se construye habrá
alcanzado mayores niveles de madurez.
**Status**: Alfa (primeras versiones, mucho por corregir, ampliar y editar.)
# Presentación
**Hackear la academía, el periodismo y otros lugares similares hegemónicos desde los que se enuncia las formas en
que se conoce y narra el mundo, es hackear, sobre todo, las formas en que se produce y circula la publicación.**
*A través de esta obra queremos experimentar sobre la relación entre conocimiento y publicación, mostrando
otras técnicas, sujetos, formatos y lugares desde los cuales la publicación puede ocurrir y cómo esta
visibiliza y da cuenta de otras voces y saberes.
Creemos que esto no sólo es beneficioso para los lugares extra-institucionales, sino para la institución misma
(academia, periodismo, editoriales), pues la intensión es iniciar una conversación largamente necesaria.*
Este es un documento abierto, experimental y colaborativo sobre como crear documentos con esas tres propiedades
y por tanto se usa a sí mismo como ejemplo, pero se puede usar para obras similares.
Hace un puentre entre la escritura como acto privado, individual y solitario y como un acto público, performativo
y colectivo, de modo similar a lo que hacen [LeanPub](http://leanpub.com/), [GitBook](https://www.gitbook.com/),
[FLOSS Manuals](https://flossmanuals.net/), o los [book sprints](https://en.wikipedia.org/wiki/Book_sprint),
pero con sensibilidades y técnicas desarrolladas y/o adaptadas desde y para el Sur Global
(aunque con alcances y aportes fuera de este).
Pone de frente lo que está en el fondo (formatos, técnicas, software) para que así repensemos
la escritura misma y los circuitos y artefactos que la soportan a esta y a su publicación.
Y también enfrenta las tensiones de esta transición y de la ocurrencia en otros sitios del
Sur Global, fuera de la institución tradicional.
Está pensado para públicos diversos y proactivos, que no son necesariamente expertos en
tecnología pero tampoco se sienten intimidados por ella.
Usa infrastructuras que encarnan los principios de agilidad y resiliencia y escarba en
artefactos digitales contruidos comunitariamente para repensar el presente y el futuro.
Debería poderse usar en procesos de aprendizaje entre pares, sin mayor lectura o preparación
previa por parte de un facilitador, sino presuponiendo que los aprendices leerán en conjunto
y usarán la obra como guía de sus actividades prácticas, así como los canales comunitarios
para lanzar preguntas sobre asuntos que no queden tan claros y visitarán futuras versiones
de este manual, que pueden conseguirse en línea en:
# Enlaces rápidos
El profesor Ulises Hernandez Pino, ha estado creando unas excelentes
[versiones en video](https://www.youtube.com/playlist?list=PLoneYj-8QRXooXKrcb9R_Pv7yAct-W6Vy)
explicando varias de las herramientas contenidas en la Documentatón (Markdown, CodiMD,
Hypothesis).
![Creación de una cuenta en Hypothesis](https://www.youtube.com/watch?v=cKf3lptMy7k width="320" height="240") ![Comentar en Hypothesis](https://www.youtube.com/watch?v=DUjjJ5Nhc4k width="320" height="240") ![Escritura colaborativa en CodiMD.](https://www.youtube.com/watch?v=lzzvu0y9Jjs width="320" height="240")
!!!
**Descargas:** La documentatón se encuentra disponible en distintos formatos.
* **Versión Breve**: [En PDF](../../uv/es/documentaton-0-2-1-breve.pdf).
* **Version Completa**: [En PDF](../../uv/es/documentaton-0-1-2-ec74f6ba0b.pdf) | [Archivos fuente (zip)](../../zip)
[Versiones anteriores](./es/changelog.md)
# Tabla de Contenidos
Esta es nuestra tabla de contenidos hasta el momento.
Los textos en azul corresponden a borradodes de los cuales ya hay un contenido desarrollado,
que puedes leer en la sección [descargas](#descargas).
**Preliminares**
- [Presentación](./es/capitulos/presentacion.md.html)
- En pocas palabras
- De esta obra
- De nuestros lectores: proactivos y diversos
- De nuestros principios: agilidad y resiliencia
- De nuestro método: meta arqueología digital activista
- De nuestras herramientas: infraestructuras de bolsillo
- Convenciones de lectura
**Parte 1: Leer Juntos**
- [Hypothes.is: anotaciones y conversaciones en línea sobre documentos](./es/capitulos/hypothesis.md.html)
- Crear una cuenta
- Acceder a su cuenta
- Acceder desde el sitio principal de Hypothesis
- Acceder desde un documento que se esté comentando en hypothesis
- Incluir documentos en su cuenta
- Subrayar textos
- Crear y etiquetar comentarios
- Responder a comentarios de otros
- Compartir sus comentarios
- Zotero: Gestionando referencias bibliográficas
- Gestionar sus referencias bibliográficas personales
- Crear o participar en grupos que comparten referencias bibliográficas
- Licenciamiento
- Cómo leer una licencia
- Como elegir una licencia
- Instaladores y gestores de Software
- Windows
- Scoop
- Chocolatey
- Gnu/Linux (y Mac)
- Nix
- Mac
- Homebrew/brew
- Varios
**Parte 2: Escribir y Publicar juntos**
- Markdown: Documentación ágil y estructurada
- Introducción
- Related tools and examples
- Learning Markdown Basics
- [HedgeDoc: Escritura síncrona](./es/capitulos/hedgedoc.md.html)
- Registro
- Crear pads
- Descargar pads
- Desde el navegador
- Con wget
- Con Pharo
- Fossil: Trabajo colaborativo distribuido
- Instalación
- En Gnu/Linux
- Usando gestores/instaladores de software
- Windows
- Trabajar con repositorios
- Navegación
- _Tickets_: Sugerencias, correcciones y planeación
- Clonación
- Modificación
- Sincronización
- Cómo resolver las bifurcaciones involutarias (forks)
- Varios
- Pandoc: Exportación multiformato
- Instalación
- Linux y MacOS
- Windows
- Exportación de Markdown a PDF
- Ejemplo: este librito/cartilla en PDF
- Edición y depuración del PDF
**Parte 3: Publicación automatizada**
- Introducción y problema generador
- Programación y *live coding*
- Pharo y Grafoscopio
- Principios básicos: Objetos y mensajes
- El texto/libro como datos
- Cierre y continuaciones
# Contacto y Ayuda
Si necesitas recibir o brindar ayuda respecto al contenido de esta obra, tenemos varias
formas de contacto:
- Para la comunidad de Grafoscopio:
- [El canal de Telegram](https://t.me/grafoscopio).
- La lista de correo:
- [Archivos históricos](https://lists.riseup.net/www/arc/grafoscopio).
- [Suscripción](https://lists.riseup.net/www/subscribe/grafoscopio).
- Para esta obra:
- Los [tiquetes de este repositorio][tickets-lista].
- La página de [hypothesis del libro][hypothesis-es].
Si tu papel es como lector o editor varias preguntas orientadoras pueden guiar tu acción:
- ¿Está este texto claro?, ¿está bien redactado?
- Si yo fuese un lector novato, ¿lo entendería o sería más un texto acompañante de una práctica
donde se explica de manera más completa lo que no está claro del todo en el texto?,
- ¿Esta traducido por completo o veo porciones en Spanglish?,
- ¿Las gráficas quedan bien escaladas cuando la exporto a distintos formatos?,
¿todas las gráficas tienen descripciones ("captions")?
El libro mismo explica en detalle los conocimientos necesarios para participar de la
cocreación del mismo.
Las reglas generales son sencillas:
- Todas las preguntas son bienvenidas, pero nos ayudas mucho a ayudarte si puedes ser muy
detallado al respecto: si ya has buscado en Internet, qué respuestas obtuviste y cómo
intentaste seguirlas; si tuviste un mensaje de error, qué es lo que dice; si estás
probando el software en qué contexto (con cuál sistema operativo y con cuáles versiones
del software).
- Si vas a aportar a un capítulo ya existente, hazlo manteniendo el estilo editorial de
la obra hasta el momento y consulta con los autores o por los medios de contacto previos,
en caso de no tener claridades que necesites antes de empezar o tengas dudas al respecto.
Puedes colaborar respondiendo a las preguntas de la parte previa, de modo que vayas
complementando y mejorando traducciones, redacción, figuras y descripciones, entre otros.
- Si quieres escribir un capítulo agrégalo al repositorio y haz un bosquejo del mismo
indicando sus subcapítulos y explica en una(s) frase(s) qué debería ir en cada una de
ellos.
Al final de uno o varios capítulos crea una lista de verificación de lo que consideras
que un aprendiz debería estar en condiciones de hacer una vez ha pasado por ellos (mira
el libro para ejemplos de tales listas de verificación).
Estas listas pueden ser escritas incluso antes de tener mayores detalles sobre los
contenidos, pues a partir de ellas podemos ver qué es necesario escribir para que los
saberes que verifican puedan ser explicados y adquiridos.
# Flujo de trabajo
Este es en líneas generales el flujo de trabajo para participar de la co-creación de esta
obra (en detalle se explican el en texto mismo):
1. Lee la [página de portada][documentaton], para que tengas claro la intensión general del trabajo y
sus métodos, públicos y herramientas, así como las formas de contacto y ayuda.
2. Para comentarnos sobre tus lecturas y sugerencias, usa la [página de hyphotesis][hypothesis-es] ó
revisa [todos los _tickets_][tickets-lista] para participar de las conversaciones o
[crea tu propio _ticket_][tickets-nuevo].
3. Escribe el texto nuevo en o fuera de línea (CodiMD o Zettlr) y agrégalo al repositorio.
4. Actualiza el repositorio para sincronizarte con los otros cambios que hayan ocurrido.
5. Haz commit de tu nuevo texto al repositorio.
6. Si se trata de una edición a un texto que ya está en el repositorio, edítalo
directamente en el repositorio y repite los pasos 3 y 4.
7. Actualiza la portada para reflejar los nuevos contenidos que has puesto.
8. Recrea los archivos derivados (PDF, EPUB, etc.) periódicamente y revisa que la
incorporación de nuevo contenido mantenga las normas estilísticas y de forma del
resultado (escalado de imágenes, metadatos propiamente adecuados, secciones y
subsecciones, etc).
9. En caso de conflictos entre los pads (CodiMD) y el repositorio (Fossil), éste
último se considera como la versión canónica del documento, pues es más fácil trazar
los cambios para documentos en Fossil, que en CodiMD.
Gracias por tu interés en participar.
Esperamos verte en cualquier de los espacios comunitarios y formas de particitación que acá
se describen.
[hypothesis-es]: https://hyp.is/go?url=https%3A%2F%2Fmutabit.com%2Frepos.fossil%2Fdocumentaton%2Fuv%2Fes%2Fdocumentaton.pdf
[documentaton]: https://mutabit.com/repos.fossil/documentaton/
[tickets-lista]: https://mutabit.com/repos.fossil/documentaton/rptview?rn=1
[tickets-nuevo]: https://mutabit.com/repos.fossil/documentaton/login?g=/repos.fossil/documentaton/tktnew&anon