Indie Web con Brea

convenciones.md at []
Login

File docs/es/convenciones.md from the latest check-in


---
titulo: Convenciones de lectura y recomendaciones
remoto: https://mutabit.com/repos.fossil/indieweb/doc/trunk/docs/es/convenciones.html
historial: ../../../../finfo?name=docs/es/convenciones.md
imagen: https://docutopia.tupale.co/uploads/upload_5d701570a9a46a4b40c7a953922b21ef.png
breaks: false
toc: true

---

Este conjunto de convenciones te ayudarán mientras estás leyendo este documento


# Tipográficas e iconográficas


  - La *cursiva* y la **negrilla** son usados para énfasis y énfasis fuerte, respectivamente
  - La citas son presentadas de esta manera:

      > Mantente alerta de las noticias y citas falsas en Internet.
      >
      > --Benjamin Franklin, 1841.

  - Las fuentes monoespaciadas son usadas para comandos y ubicaciones en el computador,
       como: copia el archivo `algo.txt` a la carpeta documentos.
  - Las jerarquías de menús gráficos de programas están organizados usando el separador `>`.
      Por ejemplo, decir "ve a `Notebook > open...`", significa que el lector debería
      hacer click en el menú `Notebook` y luego buscar el submenú `open...`
  - Los hiperenlaces se referencian con texto en rojo claro y son clicleables en las 
    versiones digitales de esta obra, por ejemplo [sitio web de la documentatón][gf]

Tenemos actividades que son más informativas y te darán una panorámica sobre un tema particular, 
mientras que otras son más prácticas.
Usamos íconos para distinguirlas:

  - <i class="fa fa-highlighter fa-fw"></i>: Lectura, en particular una variante de ella, llamada lectura 
    anotada, que explicamos en detalle en nuestro capítulo sobre Hypothesis.
  - <i class="fa fa-bolt fa-fw"></i>: Notas complementarias en vivo.
  - <i class="fa fa-code fa-fw"></i>: Código fuente.
  - <i class="fa fa-history fa-fw"></i>: Historial; usado para ver las transformaciones en el código
    fuente de una página.
  - <i class="fa fa-paper-plane fa-fw"></i>: Comparte.
  - <i class="fa fa-wrench fa-fw"></i>: Actividad práctica.
  - <i class="fa fa-play-circle fa-fw"></i> (tiempo): Ver un video. El número en paréntesis
    es la duración.  
  - <i class="fa fa-comments fa-fw"></i>: Conversación.
  
  
  
Algunos de estos íconos se encuentran dispuestos el borde de la página en la versión web de esta obra.
Ello permite su acceso rápido, particularmente durante los talleres en los que la usamos y durante
los cuales explicamos su uso en contexto en mayor detalle (por ejemplo la lectura anotada y las notas 
complementarias).

También usamos varios avisos para resaltar piezas de informacion:

:::info
:::{.admonition}
  <!-- :point_right: -->
  Usado para mostrar información resumida o resaltada de un tema particular.
  Corresponde a los llamados *call outs* del texto, que no se leen secuencialmente, sino que ayudan
  a tener una mirada panorámica y rápida de lo más importante.
:::
:::

:::success
:::{.admonition}
  Presenta una lista de verificación sobre distintas actividades que te propondremos a realizar.
  Por ejemplo:

  - [ ] Encera
  - [ ] Brilla
  - [ ] Repite
:::
:::


:::warning
:::{.admonition}
  <!-- :heavy_exclamation_mark: -->
  Usado para mostrar alguna información de la cual necesita estar al tanto.
  Por ejemplo, alguna ubicación en el disco duro, desde la cual realizar un comando, o la instalación previa de
  unos paquetes de software, así como recordatorios lecturas o conocimientos que se presuponen antes de iniciar una sesión
:::
:::

# Versiones y revisiones

Este documento es un objeto mutable y móvil.
Para identificarlo hemos usado lo que se conoce como [versionado semántico][semver], en el que
un número corresponde de manera únivoca la copia del documento que se está leyendo, siguiendo
estas convenciones:

  - La versión de la obra tiene a lo sumo tres números de la forma `x.y.z`:
      - `x` es la versión _mayor_, que habla de cambios grandes en el texto que son incompatibles con 
        la documentación del pasado, por ejemplo, si varias de las técnicas e infraestructuras 
        explicadas ha sido cambiadas sustancialmente.
      - `y` es la versión _menor_, cuando se adiciona funcionalidad de manera compatible con la 
        documentación previa, por ejemplo nuevos (sub)capítulos que explican técnicas e 
        infraestructuras nuevas o amplían las existentes.
      - `z` es la versión de _remiendo_, que se refiere a correciones que son compatibles con las 
        versiones previas, por ejemplo las ortográficas.
  - La revisión, que es una combinación de números y letras (o alfanumérica), referida a un 
    identificador único de los archivos fuentes a partir del cuales se generó la obra derivada (en 
    PDF, HTML o EPUB) y que apunta a un momento específico en los históricos de la misma.

La copia en tu poder está definida así, de forma unívoca, por dos items: la versión y la revisión que 
aparecen en la página de portada, acompañados por otros datos como los autores, el título y la 
licencia de la obra en las versiones PDF.
La versión y la revisión también aparecen en la esquina superior izquierda de las páginas en la
variante HTML[^checksum].
Ten presente tanto el número de versión como el de revisión para referirte a sugerencias o
inquietudes cuando uses nuestro [sistema de reporte de incidencias](../../../../ticket) 
o alguno de los canales comunitarios mencionados en la sección ["Acerca de esta obra"](./acerca-de.html).

[^checksum]: Si cliqueas el hiperenlace con la versión y la revisión en la esquina superior
  izquierda, verás el manifiesto de la obra, que lista todos los archivos que corresponde a la
  edición que estas leyendo y sus alfanuméricos de identidad o _checksums_.
  También encontrarás un enlace que te permite ubicar ese momento particular en el historial
  de la obra.
  Por convención, la obra más estable está en el tronco (_trunk_) del repositorio, mientras que las
  variantes se encuentran en otras ramas.
  La linea de tiempo nos permitirá explorar el historial de creación de los sitios web, su
  tronco y ramas.
  Veremos todo esto en mayor detalle en el capítulo de "[Memoria resiliente y distribuida](./memoria.html)".


:::info
  Cuando las obras alcanzan su versión `1.x` se suponen que han alcanzado un buen nivel de madurez.
  Notarás que esta obra está aún en sus versiones `0.x`, lo cual muestra su caracter de borrador
  en construcción.
  La versiones `1.x` se lograrán cuando hayamos completado la tabla de contenido propuesta en el
  menú lateral, es decir cuando tengamos cubiertos los temas que permiten instalar y usar Brea
  para personalizar temas en HTML, JavaScript y CSS, incluyendo consultas a fuentes de datos 
  diversas, expresadas en Pharo, que inyenten datos a dichos temas.

  Revisa el número de versión mayor para saber cuando hayamos alcanzado una versión estable
  y mira la sección ["Acerca de esta obra"](./acerca-de.html) en caso de que te interese aportar
  a su maduración con alguna de las formas mencionadas allí.
:::

# Conceptos y prácticas fundantes para artefactos en evolución

Como dijimos en la sección anterior, los artefactos asociados a esta obra están evolucionando
y las prácticas sobre ellos también.
Tenemos una serie de talleres quicenales que socializan y articulan lo que estamos construyendo,
así que puede que lo que no funcione en un taller en particular, lo haga en la quincena 
siguiente, pues de hecho usamos los talleres para detectar y afinar cambios y avisamos de los 
mismos por los canales comunitarios mencionados en "[Acerca de](./acerca-de.html)".
Así que podrías preguntarte si tiene sentido vincularte a estas prácticas de artefactos 
tempranos o esperar a que esté un poco más maduros para hacerlo.
Esta es una respuesta que le compete a cada cual, sin embargo la aproximación acá da cuenta
de una perspectiva en la cual no consideramos a las tecnologías digitales como acabadas
e inflexibles, sino amoldables e intervenibles.

![](https://mutabit.com/repos.fossil/doctorado-offray/doc/tip/Tesis/Escrito/TextoIntegrado/Parte2/nomad-cath.svg){width="75%"}

Por ello usamos unos conceptos y prácticas fundantes, que se pueden usar para leer, escribir
y ejecutar artefactos en evolución al margen de la madurez de los mismos.
Conceptos como objetos, mensajes, colecciones, plantillas, consultas, diccionarios y
prácticas asociadas a explorar e intervenir artefactos mientras se usan (o de _live coding_) 
vía _playgrounds_, _spotters_ y/o navegadores, serán útiles en distintos momentos.
Esto es consecuente con una búsqueda de la comunidad de Grafoscopio, sobre la idea de
explorar la inquietud por cómo cambiamos los artefactos que nos cambian.
Esto nos permite tener y entender plataformas evolutivas, para abordar problemas de 
complejidad creciente, en lugar de andar saltando de plataforma en plataforma una vez
esta se ha quedado corta para abordar nuestras necesidades.



# Recomendaciones

Un par de recomendaciones:

- **Sin copiar ni pegar!** El código, como tantos otros saberes artesanales, requiere
  de práctica y memoria muscular.
  Mucha gente cuando se enfrenta al código lo que hace es que lo copia y lo pega 
  reiteradamente, sin desarrollar dicha memoria.
  Tengo amigos que han usando por lustros y décadas Gnu/Linux en parte desde la consola de 
  comandos, pero lo que saben es que se abre una ventana negra, copian algo de un foro, lo 
  pegan y ejecutan y esperan que su problema esté resuelto, para repetir el procedimiento la 
  siguiente vez que tengan un problema.
  Sin embargo no saben qué fue lo que hicieron en esa ventana negra (la terminal o consola),
  ni cómo se resolvía su inquietud.
  
  Salvo las direcciones de Internet, código que hayamos escrito nosotras o con el que estemos
  muy familiarizados, intentaremos no copiar ni pegar, sino desarrollar estos saberes artesanales
  a través de la escritura manual, que nos permita encarnar el código y sus formas.

- **Vamos a hablar de nuestros sentipensares al respecto**: La analogía es que aterrizamos
  en un aeropuerto de un lugar cuyo lenguaje nos es desconocido y nos enfrentamos al mismo
  desde sus formas, sonoridades y costumbres entre sus hablantes.
  En este caso estamos accediendo an un lenguaje formal (el código) desde cómo se usa
  dentro de una cultura (la de lo programadores) a través de sus artefactos, una entrada a un 
  blog (código elegante), un libro, etc.
  Una vez hemos hecho el ejercicio, indagaremos no sólo por los elementos formales
  (qué pensamos del lenguaje, cómo lo experimentamos, qué preguntas nos genera) y los elementos 
  sensibles (cómo nos sentimos ante esta experiencia, qué es agradable, desagradable,
  desafiante) y podemos compartirlas en los espacios comunitarios, particularmente, si estamos 
  en el contexto de un taller 

[semver]: https://semver.org/lang/es/

# Voz, tono y pronombres

Usamos el primer nombre del plural (nosotros, nosotras) también tuteamos en algunas ocasiones,
con el fin de ser invitantes e incluyentes.
Consideramos que el lenguaje es un lugar que se repolítiza, en el sentido de que allí se expresan
luchas de poder y concepciones del mundo y suscribimos la idea de algunas feministas sobre que
tanto el plural masculino como el femenino deberían ser incluyentes y por tanto los usamos ambos y
cambiamos del uno al otro.
También entran en consideración las preocupaciones de accesibilidad cuando se reemplazan vocales
por caracteres no pronunciables claramente sin una o varias vocales acompañantes (por ejemplo 
"x" o "@"), particularmente frente a los lectores automatizados de texto que usan personas con 
visibilidad disminuida (y si bien los empleamos en interacciones más coloquiales más cortas, 
como en canales de mensajería instantánea, no hicimos uso de ellas a lo largo de la obra).

Dicho esto, este texto se encuentra cubierto por una [licencia ampliamente permisiva](./p2pmas.html), 
que permite modificaciones por personas y colectivas y explica cómo crear sitios similares.
Así que alentamos bifurcaciones y más exploraciones sobre lenguaje incluyente y nos gustaría saber 
si pudieron también hacer experimentos con lectores de pantalla y cuáles fueron los resultados, 
así como los de socializar esta obra y sus modificaciones en sus comunidades.
E invitamos a usar los métodos de contacto en el [acerca de esta obra](acerca-de.html) para que nos 
cuenten al respecto.