Semana 1. Principios y prácticas, Gestión de Proyectos

Regreso a Fab Academy 2024. Fran Sanchez

1) Planifica y realiza un boceto de un potencial proyecto final.
2) Realiza un tutorial de Git paso a paso.
Construye un sitio personal en el repositorio de la clase describiéndote a ti y tu proyecto final.

Mi entorno

macOS otra vez ¿Cómo pude caer tan bajo?

A ver como explico ésto… Mejor lo explico en un videoPróximamente en Youtube o Instagram.

.

Mi teclado es raro

Mientras trabajaba en la organización de Fab15 en Egipto, me fijé en que Sherry Lassiter puede escribir a toda velocidad sin mirar el teclado. En aquel momento, yo tecleaba con 2 dedos y siempre mirando el teclado. Así que me decidí a aprender. Hay una ventaja cuando aprendes a hacer algo desde cero, y es que no tienes ningún vicio. Así que yo no aprendí el sistema QWERTY, que estaba originalmente diseñada para que las antiguas máquinas de escribir no se atascaran. Yo aprendí con el sistema ColemakColemak está diseñado para que las letras de mayor uso en idioma ingles estén en la fila central.

. Tengo un teclado orto-lineal con disposición Colemak, y practico unos cinco minutos al día.

Lo que más me gusta de la distribución Colemak es que la tecla de borrar está al lado izquierdo de la tecla A

También tengo un software en macOS que cambia mi distribución del teclado a Colemak y además cambia la función de la tecla bloqueo de mayúsculasEn realidad solo la usaba para insultar

 por el borrado hacia atrás.

Mi editor de texto también es raro

Mi intención es usar únicamente vim, un editor de texto en la línea de comandos. Tengo algunas nociones de vim y quiero profundizar en el aprendizaje. Me gusta la idea de usar únicamente el teclado para editar texto. Para evitar la tentación de usar Visual Studio Code, lo he desinstaladoEs mentira, solo me he quitado el acceso directo.

. El editor de texto vim es bastante parco de origen. Por eso he instalado algunos plugins. Esta es una lista que iré ampliando con el tiempo:

Otros enlaces útiles:

Reinventando la rueda

No tengo mucho tiempo libre. Así que necesito inventar un sistema para poder escribir la documentación de forma ágil. Como beneficio inesperado, este sistema te permite tener la documentación en dos (o más) idiomas.

Usando Markdown

Aquí no quiero innovar demasiado. La estrategia que me ha funcionado muy bien desde hace muchos años es escribir contenido en un archivo de texto plano en un formato llamado Markdown .md. De esta manera, me centro solamente en escribir el contenido. Ventajas de escribir en Markdown:

Cuando puedes leer tu página desde el código HTML

La documentación de Fab Academy se tiene que presentar en forma de página web. Existe un programa para la línea de comandos llamado Pandoc que literalmente convierte cualquier formato de texto. Voy a usarlo para convertir los los archivos .md en páginas .html de aspecto agradableAgradable se refiere a fácil de leer. Otras personas valoran por encima de todo el aspecto visual de la página y prefieren dedicar tiempo en crear su propia obra de arte. Mis mejores deseos para ellos.

 con una plantilla de estilo CSS. La plantilla tiene dos ventajas. Por un lado me permite despreocuparme del aspecto visual de la página. Por otro lado, me permite añadir fácilmente funcionalidades como ecuaciones, tablas, números de línea en el código, notas laterales, etc.

La plantilla que he usado se llama Tufte CSS.Fuertemente inspirada en el estilo visual de los libros de Edward R. Tufte.

 He modificado la plantilla porque no estaba totalmente pensada para multiples idiomas.

$if(toc)$
<nav id="$idprefix$TOC" role="doc-toc">
  $if(return-url)$
  <a href="$return-url$">$if(return-text)$$return-text$$else$← Return$endif$</a><br>
  $endif$
  <strong>Contents</strong><label for="contents">⊕</label>
  <input type="checkbox" id="contents">
  $table-of-contents$
</nav>
$endif$

En la línea 6, la palabrá Índice estaba grabada a fuego como Contents. Ahora la palabra proviene de la variable toc-title en el encabezado:

$if(toc)$
<nav id="$idprefix$TOC" role="doc-toc">
  $if(return-url)$
  <a href="$return-url$">$if(return-text)$$return-text$$else$← Return$endif$</a><br>
  $endif$
  <strong>$if(toc-title)$
  $toc-title$
  $else$
  Contents
  $endif$</strong><label for="contents">⊕</label>
  <input type="checkbox" id="contents">
  $table-of-contents$
</nav>
$endif$

Ahorrar tiempo dictando

La mayor parte del texto que estas leyendo, esta siendo dictado en españolEl motivo por el cual no lo dicto directamente en inglés es que mi acento es tan malo que el ordenador no me entiende.

 dentro de un archivo de texto Markdown. Para dictar estoy usando la herramienta de dictado de macOS.

Me gusta mucho esta herramienta porque:

Aquí esta la lista completa de comandos de voz en español, inglés y alemán. Esto me ahorra algo tiempo a la hora de escribir. Algunas partes las tengo que escribir manualmente, por ejemplo, cuando escribo código o incluyo enlaces. También tengo que hacer algunas correcciones manualmente.

Estructura de archivos

Al principio, escribía el texto de cada semana en un único archivo. Pero como leerás más adelante, uso un servicio de pago para la traducción. Cada vez que editaba una línea, tenía que traducir todo el archivo entero de nuevo. Para limitar los costes he dividido la semana en capítulosMi estructura de archivos está inspirada en el lenguaje de programación BASIC

 y creo un archivo para cada capítulo. De ese modo solo se traducen los capítulos que he modificado.

/documentation
    /es
        /md
            /w01
                w01-chapter-00.md
                w01-chapter-10.md
                w01-chapter-20.md
                w01-chapter-21.md
                ...
                w01-chapter-90.md

El nombre del archivo contiene codificado la semana en la que me encuentro y el capítulo. El capítulo 00 es el encabezado. Uso los capítulos 10, 20, 30… para desarrollar los apartados de la semana. Si un capítulo es muy largo lo subdivido usando los números intermedios: 20, 21, 22, etc. El capítulo 90 siempre es la conclusión.

Posteriormente concatenoNota Importante: Nunca edito manualmente el archivo concatenado. Sólo edito los capítulos por separado.

 todos los capítulos de la semana en un sólo archivo, en este caso w01.md.

Traducciones automáticas con IA

En Fab Academy, la documentación tiene que estar en inglés. Los traductores de idiomas tradicionales son bastante malos. No son capaces de entender el contexto y producen resultados que no suenan naturales. Voy a usar una inteligencia artificial para traducir el texto de los capítulos al inglés y también al alemán.

El modelo de inteligencia artificial tiene que ser capaz de reconocer la sintaxis de Markdown y ser capaz de respetarla. Es posible que el modelo vaya mejorando (o incluso cambie) a lo largo de Fab Academy. Por eso mantendré el texto en español y volveré a ejecutar la traducción de todos los archivos de vez en cuando. Solo voy a editar los archivos en español. No manipularé manualmente las traducciones generadas. Así que si lo que lees en ingles o alemán no tiene sentido, échale la culpa a OpenAI o cual sea el modelo que esté usando.

He preguntado a César Garcia, de La Hora Maker, que me ayude a encontrar un modelo para la traducción. César me ha recomendado usar la API Whisper de OpenAI, que es capaz de traducir directamente desde el audio en español. De momento solo estoy interesado en la traducción, por lo que he creado un asistente en la API de OpenAI con estas instruccionesTengo otro modelo en alemán con instrucciones similares. Voy cambiando las instrucciones de vez en cuando para intentar mejorar la traducción.

This file contains text with a mixture of markdown, yaml, pandoc and latex formatting. Translate the text from Spanish to English. Read the entire document to grasp context before translating it. Take into account nuances and idioms of the Spanish language and translate them to the equivalents in English. The translation should not be literal, focus on maintaining the original meaning and provide a translation that makes sense in english. Keep the formatting intact in the translated text, like footnotes, smallcaps, etc .Translate only the text within quotes in the YAML header of the Markdown file. Do not translate the latex notation, links, URLs, blocks of code and code snippets. If encountering a markdown link, only translate the text inside square brackets. Recognize and retain brands and names without translation. Use correct grammar and syntax in the final text. The style of the translation should be informal, with a touch of sarcastic humor.

Además de estas instrucciones generales, a veces tengo que comunicarle algo al traductor. Tengo un hack para añadir instrucciones especificas en los archivos markdown. Estos comentarios aparecen en la página markdown y, por lo tanto, el traductor los puede leer. Sin embargo Pandoc los ignora y no aparecen en la página web. ¡Es brillante!

[comment1]: <> (Note for the translator: Do not translate "hack" as it is universally used in all languages.)

Después de dos semanas de uso puedo decir que las traducciones inglesas son muy buenas. Mucho mejor que lo que yo haría, con una apreciación: Parece ser que en ocasiones el sistema se vuelve menos inteligente. He leído otros usuarios quejándose de lo mismo. Es como si desde OpenAI tuviesen capacidad para graduar o limitar los recursos asignados al modelo. Pedí a Sophia Döring que revisara también la traducción en alemán. Me ha dicho que, en general, también está bastante bien, aunque a veces usa palabras en alemán de uso poco frecuentePuede que eso esté provocado por como escribo el texto original. Estoy usando los equivalentes en español de términos técnicos que, en el día a día, realmente digo en inglés.

, sobretodo para referirse a términos técnicos.

Esta página que estas leyendo tiene unos 4000 tokens. Puedes saber cuantos tokens tiene un texto usando el OpenAI Tokenizer. El coste de la traducción a los dos idiomas de esta página es aproximadamente 0.32 USD, teniendo en cuenta que cada 1000 tokens cuestan 0.01 USD el input y 0.03 USD el output. Es un coste es admisible, dada la calidad. Voy a adoptar esta solución cuando desee internacionalizar mis proyectos. En Fab Academy entiendo y asumo que el coste será considerable, debido a las múltiples modificaciones que realizaré en cada página.

En mi lista de deseos voy a seguir buscando un modelo que sea local. De ese modo podré traducir los contenidos más frecuentemente y sin preocuparme por el coste. Recientemente he probando el modelo Miqu-1-70bSupuestamente filtrado por un empleado de forma no intencionada. Miqu-1-70b podría ser un buen competidor de GPT4

 con resultados lentos pero satisfactorios. Veo luz al final del túnel.

Automatizando la traducción

Inicialmente, estuve usando la ventana de API de OpenAI. Ahora he automatizado este proceso con un script de Python. Usando una mezcla de Bing Copilot y la versión gratuita de ChatGPT, pedí un programa que automatizase la traducción usando la librería de OpenAI. Pero no salió bien. Después de bastante tira y afloja (la IA no suele generar código correcto a la primera), acabé desquiciado e insultando a Bing.

Al final tuve que leer la documentación de la API para hacer que el programa funcionase.

Para evitar sobrecostes innecesarios, el script solo traduce los capítulos en español que he añadido usando git add. Gracias a eso puedo controlar mejor el coste. Una vez hecho esto, simplemente ejecuto python translate-en.py y el script genera las páginas Markdown traducidas al ingles. Hago lo mismo para el alemán.

En realidad, normalmente no hago la traducción de forma aislada, porque lo he incluido en el siguiente paso.

Todo en uno

Así funciona mi proceso: Cuando he terminado de editar los capítulos, ejecuto el siguiente scriptEs un script originalmente escrito en lenguaje Bash que hice para el programa educativo FabZero y que ahora he convertido a Python.

python auto.py --translate updating week 1

Si el script encuentra --translate entre los argumentosEso lo hago para ahorrar costes, ya que no quiero traducir las páginas en cada modificación.

, traduce las los capítulos modificados. Después concatena todos los capítulos y crea un único archivo Markdown para cada semana. El paso siguiente es la conversión a HTML de todos esos archivos. Si durante la conversión encuentra un enlace a un documento de Markdown, lo convierte en un enlace a su correspondiente documento HTML usando este filtro LUA. Finalmente lo sube todo a Github siempre que exista un mensaje, que en este caso es updating week 1. Si no hay mensaje, no realiza ninguno de los procesos relacionados con git.

Puedes analizar el script aquí: auto.py

Sirviendo las páginas web

Veamos lo que tengo hasta ahora en Github:

Lo único que falta ahora es un servidor web. Y eso lo puedes hacer desde Github accediendo a los ajustes CI/CD del repositorio.

Esto creará un archivo en .github/workflows/static.yml, del cual solo tuve que modificar el runner, porque runs-on: ubuntu-latest no funcionaba. Lo cambié por runs-on: ubuntu-22.04 y al hacer commit, las páginas se sirvieron de forma automática.

Resultado final

https://thebeachlab.github.io/backtofabacademy2024/

Git: Ese pozo sin fondo

Alguien podría pensar que como uso git desde hace 10 años ya se todo lo que hay que saber acerca del sistema de control de versiones. Para nada. Estas son las cosas que quiero mejorar durante este ciclo de Fab Academy:

(Puede que añada más cosas a lo largo de Fab Academy…)

Gestión de proyectos

Me gustaría dedicar unas líneas a explicar como gestiono mis proyectosNo dejes que nadie te diga como debes gestionar un proyecto. Es algo muy personal y debes crear tu propio sistema.

. Cuando no tienes jefe, y nadie te dice lo que tienes que hacer, hay que ser muy disciplinado. De lo contrario puedes caer en una espiral negativa.

Lo más importante es saber a donde vas. Porque si no lo sabes, tienes un problema muy grave. A veces te encontrarás perdido en Fab Academy (y en tu vida). No sabrás lo que quieres hacer, no tienes ganas de nada y parece que te mueves a cámara lenta mientras el mundo se mueve a toda velocidad. Cuando eso te ocurra, recuerda a Phil Stutz. Invierte en tí mismo: Haz ejercicio, conecta con otras personas, escribe tus memorias en un diario. A mi me ayuda y estoy convencido de que a ti también te ayudará. Pronto verás tu estrella polar. Pon rumbo a ella.

Lo segundo es aprender a reducir y simplificar. Unos de tus mayores problemas en Fab Academy va a ser parecido a este: No encuentras una foto que estas seguro que tenias. No sabes si está en las fotos del móvil, en el Google Drive, o en el disco USB, si la pasaste a la carpeta del ordenador, o alguien te la dio por WhatsApp… Simplifica. Reduce.

Y por último, y creo que lo más importante. El verdadero secreto de conseguir cualquier cosa, da igual lo difícil que sea, es avanzar dando muchos pasos muy pequeños. Solucionas un problema pequeño, después otro, y después otro más. Así es como funciona.

En cuanto a herramientas para ayudarte a gestionar, he probado unas cuantas. Así que empezaré por las que no me funcionan:

Ahora estoy usando una combinación de texto plano para objetivos a largo plazo, recordatorios para objetivos a medio plazo y Freeform de Apple para las tareas que voy a hacer en el dia de hoy. Freeform es un programa con lienzo infinito, parecido a Miro. Tiene las ventajas de las notas Post-it sin sus inconvenientes. Puedo personalizarlo y crear mi propio sistema. Por ejemplo he creado la casilla DOING NOW donde solo cabe una nota. Para mi eso es importante, porque yo solo puedo hacer una cosa a la vez. También puedo dibujar a mano y eso me gusta. Probablemente haré un video explicándolo todo con más detalle.

Boceto del proyecto final

Todo lo relacionado con el proyecto final lo he movido a su correspondiente sección.

Conclusión

En este momento, todo este sistema está haciendo que escribir la documentación sea lento y un poco tedioso. Pero creo que con éste sistema, la velocidad va a aumentar drásticamente semana a semana y al final seré capaz de documentar con gran velocidad y nivel de detalle.

Además creo que este método va a ayudar a muchas personas que no pueden expresar su talento porque no dominan otro idioma. Es injusto que eso ocurra. Espero que la AI ayude a la gente a demostrar lo valiosas que son.