En los últimos 18 meses, he lanzado casi 200 versiones de mi aplicación web para clientes de pago. Y todavía no estoy oficialmente en la versión 1.0. Entonces, la semana pasada, cuando lancé la versión 0.9.24.25 a través de mi plataforma sin código, Bubble.io, rompí… bueno, casi todo.
Peor aún, no fue un hackeo catastrófico que pudo detectarse en unos pocos minutos de prueba. Pero unos días después, el cliente contactó a soporte con un problema extraño. Esto me hizo descubrir una falla en mi lógica que nunca hubiera notado de otra manera. Podría haberse retrasado durante días y haber hecho un gran lío con mis datos.
Afortunadamente, pude volver a mi documentación, averiguar qué hice y cuándo lo hice, y solucionar el problema rápidamente. Tardé unos cinco minutos en encontrar y solucionar el bloqueo, y solo afectó a un cliente. Si parece que he estado hablando de documentación recientemente, es porque lo he estado, por una buena razón. Sin la documentación en este caso, podría haberme tomado semanas darme cuenta de lo que había hecho y posiblemente el mismo tiempo para solucionarlo. Mientras que el ingreso se deslizó a través de un enorme agujero en mi solicitud.
Sin código no es broma.
Sí, necesita documentar el código que no escribió
Soy un antiguo desarrollador (en recuperación). Y una de las razones por las que me encanta programar es porque No hay necesidad hay que hacer, como configurar la infraestructura, reconstruir muchas ruedas funcionales y aprender y memorizar las complejidades de la sintaxis. Pero hay una práctica que definitivamente mantuve de mis días de desarrollo porque recuerdo lo difícil que era arreglar las cosas cuando la gente me gritaba.
Por extraño que parezca un concepto como «documentar sin código», es extremadamente importante no solo para la recuperación de errores, sino también para no perderse en la maleza cuando está creando una aplicación más grande y más amplia o sirviendo a un mercado más amplio.
La buena noticia es que no es necesario ser desarrollador para documentar correctamente el código que falta. La mala noticia es que no existe un formulario, formato o incluso un repositorio central para realizar un seguimiento de todas las partes de su aplicación configuradas en todas las plataformas.
Pero, de nuevo, como ex desarrollador, empresario de toda la vida y ahora no programador experimentado con un un negocio que funciona y es rentable construido exclusivamente en plataformas sin código y de código bajo, creo que tengo una buena solución.
Haz lo que te funcione, pero asegúrate de seguir estos seis principios.
6 consejos para documentar su software sin código
- Crear un único documento central
- Documenta antes de actuar
- Sea detallado pero directo
- Documente no solo lo que hizo, sino también por qué.
- Sea juicioso acerca de lo que hace el lanzamiento
- No confíe en las versiones de la plataforma
1. Crea un único documento central
La razón principal por la que los no codificadores no documentan es porque no hay dónde hacerlo. Es una razón tonta hasta que lo piensas. Cuando no está escribiendo código, no hay espacio para comentarios. Tampoco hay GitHub, ningún lugar central único donde se lleva a cabo su trabajo.
Por ejemplo, en este momento uso principalmente Bubble.io como base para mi conexión de MailChimp, que estoy personalizando en gran medida, y también estoy ajustando un poco a Stripe, uniéndolo todo junto con Zapier como cinta adhesiva y superponiendo capas. en cuatro o cinco programas adicionales
Pero hay un secreto del desarrollador. Los buenos desarrolladores mantienen un cuaderno abierto cuando codifican, como en un editor de texto o un documento de Google, solo para realizar un seguimiento de su lógica mientras intentan hacer una docena de cosas diferentes a la vez. La decodificación no es realmente otra cosa. Me gusta usar un Documento de Google y tenerlo abierto todo el tiempo.
2. Documenta antes de actuar
Nunca toco una configuración, conecto un webhook o incluso cambio un tipo de fuente sin escribir lo que voy a hacer antes de hacerlo.
Documentar el código a posteriori por lo general conduce a dos errores. Primero, no lo hace porque si sabe cómo construir, dedica todo su tiempo disponible (y algo más) a construir. Segundo, no recuerdas al menos la mitad de lo que acabas de hacer, especialmente no en detalle.
Documentar antes del hecho requiere paciencia y dedicación, pero vale la pena, especialmente cuando ha terminado de «codificar» y solo necesita marcar todo lo que acaba de hacer en lugar de escribir todo desde cero.
3. Sea detallado pero directo
Explica detalladamente todo lo que vas a hacer. Vuelva al documento para obtener ayuda mientras trabaja actual los nombres de plataformas, objetos, funciones, datos y nombres de variables, todo lo que acaba de crear y tocar.
Imagina escribir un artículo para alguien que no seas tú, alguien que camina en el frío sin tener idea de lo que estás haciendo. Porque si tienes éxito, lo más probable es que así sea. Cuando vendí una de mis empresas hace años, trajeron su propio CTO para una transferencia de tecnología estándar, y me senté con esa persona durante un mes para desmitificar mi (bastante bien documentado) laberinto de código.
Pero también sé directo. No escriba páginas de documentación, escriba viñetas breves. Áreas clave en negrita o diferentes plataformas para que pueda desplazarse por su documento y ver de un vistazo dónde podría estar su problema.
Además, asegúrese de registrar la fecha en que realizó el cambio y la fecha en que se lanzó la nueva versión. Utilice la numeración de versión correcta cada vez que publique. Y manténgase alejado de abreviaturas, acrónimos o cualquiera de su idioma.
ejemplo:
- Versión 0.9.23.1 – activa el 02/06/22, todo funcionando el 02/06/22
- administración [not the actual page name] en la burbuja
- Se agregaron indicadores de asesor y escritor para actualizar la interfaz de usuario y ambos campos de datos para actualizar la secuencia de comandos del usuario en el flujo de trabajo
- revisión [not the actual page name] en la burbuja
- Botón de notificación agregado para actualizar la interfaz de usuario de la pregunta cuando editstep = «published»
- El script de flujo de trabajo del botón agrega Notificado a los datos de la nota del editor solo si aún no está allí.
- El botón de flujo de trabajo envía correos electrónicos al usuario = asesor si aún no han sido notificados
- Usuario = asesor con binario = sí recibe correo electrónico de BCC
- [more stuff]
4. Documenta no solo lo que hiciste, sino también por qué
Aquí hay otro secreto del desarrollador. Una de las principales razones por las que el software falla es porque al desarrollador se le dio algo con lo que trabajar pero no entendió Por qué funcionó. Funcionó, así que enviaron el código. Luego se rompió y ahora no pueden entender por qué se rompió porque solía funcionar.
«Hasta» significa el tiempo hasta que se realicen otros cien cambios en el código base después de que se implemente este código con fugas.
Los no programadores caerán en esta trampa una y otra vez porque las plataformas son tan inteligentes que harán que casi cualquier cosa que puedas hacer «funcione». Hasta que sucede. Así que haz un esfuerzo adicional para comprender por qué haces lo que haces y luego anótalo. De esa manera, cuando pasen algunas semanas o meses, no perderá la cabeza tratando de averiguar por qué lo hizo de la manera en que lo hizo.
ejemplo:
- Versión 0.9.22.4 – activa el 18/05/22, todo funcionando el 18/05/22
- [something I did] en vejiga
- El estado «Cancelar» significa que tengo que cancelarlos manualmente y obtener un reembolso dentro de los 3 días posteriores a la renovación (automatizar esto más adelante). De lo contrario, se cancelarán automáticamente al final del período de facturación.
5. Sea juicioso sobre lo que hace el lanzamiento
No insista en la producción inmediatamente. Tienes que equilibrarte entre derribar muchos carritos de manzanas pequeños y derribar un carrito de manzanas enorme. Pero créanme, los carritos de manzanas más pequeños son mucho más fáciles de limpiar.
Por lo general, a menos que se trate de una revisión rápida, el único recurso para un error de producción es retroceder a una versión anterior. Muchas plataformas son muy buenas en esto, pero si ha pasado semanas o meses trabajando en un lanzamiento y entregándolo todo de una vez, estará buscando una aguja en un pajar, enviando a sus clientes de vuelta a una versión que podría ser terriblemente viejo
ejemplo:
- Versión 0.9.20.17 – activa el 13/03/22, todo funcionando el 13/03/22
- El enlace del autor en la IU de respuesta ahora apunta a la página del consultor en Bubble
Eso es todo. Aquí está la versión completa. Hace más de lo que piensas, pero no mucho más.
6. No confíe en el control de versiones de la plataforma
Algunas plataformas le permiten crear puntos de guardado y restaurar versiones anteriores como mencioné anteriormente, pero la mayoría no lo hace bien y algunas no lo hacen en absoluto. Haga sus propias copias de seguridad de texto, scripts que haya cambiado, configuraciones que haya cambiado, cualquier cosa que requiera mucho replanteamiento para rehacer.
Escribir un gran código no se trata de conocer palabras e idiomas secretos que nadie más conoce. Se trata de hacer que las aplicaciones hagan grandes cosas con elegancia. Requiere mucha imaginación, perseverancia y tiempo. No deje que su mejor pensamiento crítico se pierda cuando esté lidiando con un millón de otras cosas relacionadas con la gestión de un negocio.