Cómo utilizar un Wiki para la documentación de proyectos

Beneficios de instalar una Wiki para la documentación

Incluso en los estudios de desarrollo bien organizados, mantener la documentación puede ser un desafío, especialmente durante la fase de implementación. A menudo, la documentación se convierte en un pensamiento posterior. A la hora de transcribir la documentación, se puede perder exactitud.

¿Cómo proporcionar documentación oportuna y de fácil acceso?

La solución es instalar una WikiWikiWeb o Wiki, en resumen.

¿Qué es una Wiki?

"Wiki Wiki" significa "rápido" en hawaiano, y es un nombre apropiado. Una Wiki es un sitio web editado de forma colaborativa diseñado para promover la acumulación y mejora de datos con la menor complicación posible. Cualquier usuario que vea una Wiki puede editar fácil y rápidamente cualquier cosa que vea. Usar una Wiki es como navegar por una colección de páginas de procesador de texto vinculadas. No es necesario saber HTML o ningún otro lenguaje de marcado para contribuir a una Wiki.

La primera Wiki se encontraba en el Repositorio de Patrones de Portland. Aún está en uso activo y tiene más de 20,000 páginas de Wiki, incluida una página de preguntas frecuentes de Wiki Wiki Web. A partir de ese primer ejemplo, se han creado miles de otras Wikis. Docenas de paquetes de software ofrecen funcionalidad de Wiki. Las Wikis pueden ser públicas o internas de una empresa.

Instalación de la Wiki

Antes de poder comenzar a documentar en una Wiki, debes instalar una. Una búsqueda rápida en la web revelará una amplia variedad de programas de software para Wikis, todos ellos con las mismas características básicas. Difieren en los lenguajes en los que están escritos, los requisitos del servidor web y del sistema operativo, y las funciones auxiliares que brindan.

He probado muchos de los paquetes de software de Wiki disponibles y prefiero uno gratuito llamado MoinMoinWiki. MoinMoin tiene la combinación perfecta de facilidad de uso, facilidad de instalación y poder. También está disponible para las plataformas del servidor Windows, Linux y Mac OSX.

Aprovecha al máximo el encadenamiento de excepciones en Java 1.4

Después de descargar el software MoinMoin, sigue las sencillas instrucciones de instalación. En poco tiempo tendrás tu propia Wiki.

Uso de la Wiki

Una vez que hayas instalado tu Wiki, navega hasta ella con tu navegador web y echa un vistazo a la página de inicio (ver Figura A). Tiene algunas instrucciones generales sobre cómo usar una Wiki que pocas personas realmente leerán. Puedes personalizar rápidamente la página de inicio a tu gusto.

Haz clic en el enlace "Editar texto" en la parte inferior de la página. El navegador mostrará un área de texto grande que contiene el texto completo de la página que acabas de ver, como se muestra en la Figura B. En este punto, tienes dos opciones. Puedes agregar texto que tus compañeros realmente leerán sobre lo que ya está allí, o puedes simplemente reemplazar todo.

No importa mucho qué texto decidas agregar en este momento. Todas las páginas de Wiki se revisarán una y otra vez, pero ninguna tanto como la página de inicio. Normalmente empiezo una nueva Wiki con un breve texto introductorio y enlaces a algunas páginas que pueden ser rápidamente pobladas por usuarios nuevos de Wiki. Exploraré algunos ejemplos más adelante en este artículo.

Por supuesto, esto nos lleva a la pregunta "¿Cómo se agregan enlaces a una página de Wiki?" El proceso no podría ser más fácil. Para crear un enlace en una página de Wiki, simplemente coloca dos palabras en mayúscula una al lado de la otra sin espacio entre ellas. Por ejemplo, en esta oración, la cadena WikiWord sería un enlace. Enlazaría a una página de Wiki llamada WikiWord. Si, al navegar por la Wiki, un usuario hace clic en el enlace WikiWord, se le llevará a la página de WikiWord si existe, o se le preguntará si desea crear la nueva página WikiWord.

Esta sintaxis simple de enlaces, junto con la capacidad de enlazar a páginas que aún no existen sin obtener un error 404 desagradable, permite un crecimiento fácil y orgánico de la Wiki. Por ejemplo, podrías estar escribiendo una página sobre Linux e incluir la palabra LinusTorvalds, omitiendo intencionalmente el espacio para crear un enlace, sin intención de crear una página LinusTorvalds. Si más tarde alguien está leyendo esa página de Linux y cree que sabe algo sobre el Sr. Torvalds, puede hacer clic en el enlace, elegir crear la página y escribir algunas frases sobre el tema, que a su vez pueden incluir enlaces a otras páginas de Wiki inexistentes que se crearán más adelante.

Cómo trabajar con archivos de texto en Visual Basic .NET

Promocionando la Wiki

Después de crear tu Wiki, descubrirás que se necesita muy poco esfuerzo para trasladar los esfuerzos de documentación a la misma. Lo único que debes hacer es crear un poco de contenido que tus futuros conversos encuentren convincente. El mejor lugar para empezar es en la página de inicio. Normalmente elimino la mayor parte del contenido incorporado en la página de inicio y lo reemplazo con enlaces como CompañíaEmpleados, EnlacesDocumentación, RecursosExternos y CosasDivertidas. Luego, creo estas páginas haciendo clic en los enlaces y aceptando crear las nuevas páginas cuando se me pida que lo haga. En la página CompañíaEmpleados, coloco un enlace para cada uno de los desarrolladores del proyecto. Los nombres son excelentes enlaces de Wiki y es raro que un desarrollador no haga clic en su propio nombre de enlace roto para crear su propia página de Wiki personal.

Las otras páginas pueden contener URL sencillos que el software de Wiki también convertirá en enlaces hacer clic cuando se muestren. Recopilar enlaces a todos los documentos internos y externos a los que los desarrolladores del proyecto se refieren con frecuencia proporciona una especie de página de marcadores compartidos conveniente. A menudo, esto es suficiente para atraer a otros hacia el mundo de la Wiki por sí solo.

Viviendo la vida Wiki

Una vez que tengas contenido en la Wiki, necesitas comenzar a promoverla como el lugar donde encontrar recursos y detalles del proyecto. Responde tantas solicitudes de información como sea posible con un simple "Está en la Wiki", incluso si tienes que ingresar rápidamente la información solicitada antes de que el solicitante tenga la oportunidad de buscarla.

La Wiki es un lugar maravilloso para almacenar pequeñas piezas de conocimiento que no son lo suficientemente grandes como para tener sus propios documentos. Información de cuentas de desarrollo, fechas límite y consejos y trucos variados son excelentes contenidos para una Wiki. Antes de darte cuenta, descubrirás que la Wiki es el primer lugar al que los miembros del proyecto acuden cuando intentan encontrar una pequeña información.

Arquitecturas de Clustering para Aplicaciones Empresariales: Escalabilidad y Disponibilidad

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 Cómo utilizar un Wiki para la documentación de proyectos , tenemos lo ultimo en tecnología 2023.