Cómo leer guías

Cómo leer una guía

Cuando queremos configurar software siempre hay alguien que lo intentó antes que nosotras y documentó el proceso. Sin embargo muchas veces las guías son difíciles de entender, están incompletas, desactualizadas o directamente no las encontramos. Este artículo tiene varias recomendaciones para trabajar con guías encontradas en Internet.

Ninguna guía es literal

Aunque una guía venga con todos los comandos que la persona que la escribió usó para configurar un programa, esto no quiere decir que van a funcionar en tu sistema tal cual. La regla primordial es no copies y pegues. Correr comandos sin saber qué hacen es muy peligroso y además no nos ayuda a entender lo que estamos haciendo. Aprender cosas toma tiempo, no te apures.

A veces las guías se hacen a las apuradas y sólo contienen los comandos que se corrieron, sin ningún tipo de explicación. A veces cuando pedís ayuda alguna persona te dice los comandos que cree que deberías correr, sin darte o pedirte contexto, o te dice los comandos que necesita para tener ella misma contexto. Cuando estés frente a alguno de estos casos, huí.

Muchas guías tienen una mínima explicación de qué significa cada cosa, pero también tienen el comando en un recuadro especial y remarcado con colores. Todo parece indicar que es exactamente lo que necesitamos, entonces lo copiamos y pegamos:

rm -rf /

Pero si no leés lo que dice alrededor, seguro no te diste cuenta que el comando anterior borra tu sistema completo.

Otra de las razones por las que las guías no se deben utilizar literalmente, al pie de la letra, es que las instrucciones a veces deben adaptarse a cada sistema, por lo que la otra persona puede hacer un esfuerzo (o no) por indicarte que debés cambiar algo:

rm -rf carpeta

Este es el más básico. Quiere decir que donde dice carpeta cambies el comando por la carpeta que estás queriendo borrar. A menos que tengas una carpeta llamada así, ese comando no va a borrar nada.

rm -rf $carpeta

Algunos lenguajes de programación usan el signo pesos ($) para indicar que lo que sigue es una variable. Las personas que trabajan con este tipo de lenguajes suelen indicarlas de esta forma (aunque hay lenguajes que no usan ningún símbolo para indicar variables). Quiere decir que tenés que cambiar $carpeta entero, en vez de dejar el signo $ y cambiar sólo carpeta.

rm -rf CARPETA

Una variante de la primera.

rm -rf {{carpeta}}

Esta es la sintaxis de plantillas de sitios web, que se usa en varios lenguajes. No hay que dejar las llaves.

rm -rf carpetaX

Y acá hay que cambiar la X por un número...

Así hay varias formas de indicarte que el comando que acabás de copiar y pegar en realidad lo tenías que adaptar a tu sistema.

Ninguna guía es completa

Muchas veces al seguir una guía nos damos cuenta que hay pasos que faltan, o que al terminarla el voilá! era una promesa vacía. Hay que tener en cuenta que las guías se suelen escribir como resumen, al terminar de configurar un servicio después de varios días de prueba y error, siguiendo otras guías igual de incompletas.

A todo el mundo le cuesta configurar un programa y documentar esa experiencia es un proceso cansador. Leé varias guías. Comparalas. Descartá las más antiguas, las menos explicadas.

En todo caso, no vas a poder reproducir en cinco minutos el sufrimiento o proceso de aprendizaje de varios días de otra persona.

Nadie documenta los problemas

Las guías suelen documentar el proceso que funcionó, pero no sus fallos. Si al terminar de seguir una guía tenés errores, lo mejor que podés hacer es buscarlos individualmente. Si pedís ayuda, no empieces con "no funciona", tratá de dar la mayor cantidad de datos posible, lo que probaste y no funcionó.

En caso de duda, RTFM

Siempre hay que referirse a la documentación original. Si tenés dudas con un comando, leé su manual:

man rm

Donde rm es el comando que querés investigar. También pasan cosas locas con man man.

Hay gente que parece que sabe demasiado y tiene el tiempo libre para enseñarte a hacerlo. Ahorrales tiempo y frustración investigando por tu cuenta, demostrando interés y ganas de aprender. Todas aprendimos igual.