El problema de la mala documentación en Nextcloud y otros software

Quiero comenzar esto pidiéndote, querido lector, que no lo tomes tan en serio como suena. Nació de un lugar de frustración, pero también desde un lugar de respeto y un toque de humor. Dicho esto, recientemente estaba trabajando con una instalación de Nextcloud cuando sucedió algo extraño. Quería instalar una aplicación compatible con la implementación y procedí como siempre, instalando desde la sección de Aplicaciones de mi cuenta de administrador. Encontré la aplicación que quería instalar, hice clic en Descargar y Activar, y Nextcloud se puso manos a la obra para hacerlo realidad.

Solo que las cosas no salieron como se había planeado. Justo cuando la instalación de la aplicación se completó, Nextcloud mostró una página de error. No importa lo que hice, no pude regresar a la GUI para solucionar el problema. Dado que esto no era una máquina virtual, no pude revertir una instantánea.

¿Qué debía hacer? Tomé un riesgo y logré resolver el problema (más sobre esa solución en un momento).

Este problema plantea un par de problemas con Nextcloud y con mucho otro software por ahí. El primero es cuando una extensión está listada como compatible, el simple acto de instalar ese complemento no debería arruinar todo el sistema. Es una extensión, no un kernel o los cimientos de todo. El segundo problema es mucho más importante, y al igual que el primero, no se limita a Nextcloud. Ese problema es la documentación.

Seamos honestos aquí, la documentación deficiente o insuficiente es un problema generalizado. Cuando el software en cuestión es de código abierto, es posible que no tenga una compañía a la que acudir en busca de ayuda. Cuando esto sucede, los usuarios y administradores a menudo se encuentran en la oscuridad, tratando de resolver problemas por su cuenta. Debido a esto, aquellos responsables de las aplicaciones deben priorizar una documentación adecuada, clara y actualizada.

Por supuesto, este punto es algo discutible cuando tienes un usuario o administrador capaz de sumergirse en todo tipo de problemas para resolver una situación que no debería haber ocurrido o que debería ser más fácil de solucionar, gracias a una documentación adecuada.

Las demandas de los programadores: JavaScript

Esto me ha sucedido con muchos proyectos que he utilizado o intentado utilizar, desde los más pequeños hasta los más grandes. No puedo decirte cuántas veces me he adentrado en el mundo de Kubernetes solo para descubrir que su documentación estaba desactualizada y que lo que intentaba hacer fallaba. Esa es la documentación oficial de un proyecto reconocido como el mejor orquestador de contenedores en el mercado. He encontrado problemas similares con la documentación de Google. Sinceramente, ha pasado mucho tiempo desde la última vez que encontré documentación actualizada, concisa, clara y bien escrita.

Este problema es tan grave que a menudo he pensado en ofrecer mis servicios a empresas con el único propósito de mejorar su documentación. Luego recuerdo cuántas empresas se preocupan tan poco por la documentación que prefieren dejar a los usuarios y administradores a su suerte en lugar de invertir el dinero y el esfuerzo necesario para mantener su documentación al nivel de su producto.

Es un triste estado de cosas. ¿Qué tan malo es? Es tan malo que intentaba resolver ese problema con Nextcloud y me frustré lo suficiente como para escribir este artículo en su lugar; eso es lo extendido que está la mala documentación.

¿Cuál era el problema?

En pocas palabras, estaba intentando conectar una instancia de Nextcloud a un proveedor de almacenamiento externo. Inicié sesión en mi instancia de Nextcloud y todo salió como describí anteriormente.

Fue un desastre.

Al final, la solución fue realmente muy simple. Inicié sesión en el servidor a través de SSH y eliminé la carpeta de la aplicación que causaba el problema en /var/www/html/nextcloud/apps. El siguiente comando solucionó el problema:

Cómo instalar Podman en Ubuntu: Guía paso a paso

sudo rm -rf /var/www/html/nextcloud/apps/files_external_dropbox

Fui afortunado con algunas cosas:

1. Recordé qué aplicación causó el problema.
2. Tenía las habilidades para solucionar el problema por mi cuenta.
3. Este no era un servidor de producción para un cliente.

En otras palabras, la situación podría haber sido mucho peor. Por supuesto, si este fuera un servidor de producción, habría tenido la opción de usar una instantánea o una copia de seguridad.

No debería haber llegado a esto, pero ocurre con bastante frecuencia. Los administradores y usuarios en todas partes se encuentran en situaciones similares, donde la documentación no les sirve de nada y terminan teniendo que depender del soporte de la empresa (que a menudo es una frustración en sí misma) o resolver las cosas por su cuenta.

Esto es especialmente cierto en el caso del software nativo de la nube moderna que se actualiza constantemente con CI/CD y DevOps, donde nadie tiene tiempo para documentar todo en la misma escala, alcance y velocidad a la que evoluciona el software.

Es un problema sin una solución clara.

Visual Studio Code en Raspberry Pi: Una combinación poderosa y flexible para desarrollo

Lo cual, por supuesto, es mejor que una solución sin un problema claro, que a menudo es el caso en el mundo ágil de hoy, lleno de palabras de moda y tecnología por el mero hecho de la tecnología.

De vez en cuando, solo quiero gritar al vacío: "¡Algo más lento en el desarrollo de aplicaciones o más rápido en la documentación!". De cualquier manera, estas dos tareas necesitan alcanzar cierta sincronización antes de que los usuarios se cansen y busquen otras soluciones, nativas de la nube o no.

Suscríbete al canal de YouTube Cómo hacer que la tecnología funcione de Newsmatic para obtener los últimos consejos tecnológicos para profesionales de negocios de Jack Wallen.

En Newsmatic nos especializamos en tecnología de vanguardia, contamos con los artículos mas novedosos sobre Desarrollo, allí encontraras muchos artículos similares a El problema de la mala documentación en Nextcloud y otros software , tenemos lo ultimo en tecnología 2023.