README – cómo saber

Los archivos README tienen una larga tradición en los proyectos de software. Originalmente, estos archivos de texto sin formato contenían información sobre la licencia e instrucciones sobre cómo compilar el artefacto correspondiente a partir del código fuente o notas importantes sobre la instalación del programa. No existe ningún estándar real sobre cómo construir un archivo README de este tipo.

Desde que GitHub (adquirida por Microsoft en 2018) inició su marcha triunfal como plataforma de alojamiento de código libre para proyectos de código abierto, existe desde bastante pronto la función de mostrar el archivo README como página de inicio del repositorio. Todo lo que se necesita es crear un simple archivo de texto llamado README.md en el directorio raíz del repositorio.

Para poder estructurar los archivos README de forma más clara, se buscó una posibilidad de formato simple. Rápidamente se eligió la notación markdown porque es fácil de usar y se puede renderizar de forma bastante eficiente. Esto facilita la lectura de las páginas de resumen y permite utilizarlas como documentación del proyecto.

Es posible enlazar varios archivos markdown como documentación del proyecto. Así se crea una especie de mini WIKI que se incluye en el proyecto y también se versiona a través de Git.

El asunto tuvo tanto éxito que soluciones de autoalojamiento como GitLab o la comercial BitBucket también han adoptado esta función.

Ahora, sin embargo, se plantea la cuestión de qué contenido es mejor escribir en un archivo README de este tipo para que también represente un verdadero valor añadido para los forasteros. Con el paso del tiempo, se han establecido los siguientes puntos:

  • Breve descripción del proyecto
  • Condiciones de uso del código fuente (licencia)
  • Cómo utilizar el proyecto (por ejemplo, instrucciones para compilar o cómo integrar la biblioteca en proyectos propios)
  • Quiénes son los autores del proyecto y cómo se puede contactar con ellos
  • Qué hacer si desea apoyar el proyecto

Mientras tanto, las llamadas insignias (pegatinas) se han hecho muy populares. A menudo hacen referencia a servicios externos, como el servidor gratuito de integración continua TravisCI. Ayudan a evaluar la calidad del proyecto.

También hay varias plantillas para archivos README en GitHub. Sin embargo, tienes que fijarte en las circunstancias reales de tu propio proyecto y juzgar qué información es realmente relevante para los usuarios. Estas plantillas ayudan mucho a averiguar si se ha pasado por alto algún punto.

El hecho de que prácticamente todos los fabricantes de soluciones de servidores de gestión de control de código fuente hayan integrado ya la función de mostrar el archivo README.md como página de inicio del proyecto para el repositorio de código significa que un README.me también es algo útil para los proyectos comerciales.

Aunque la sintaxis para markdown es fácil de aprender, puede ser más conveniente utilizar directamente un editor MARKDOWN para la edición extensiva de este tipo de archivos. Debes asegurarte de que la vista previa también se muestra correctamente y no se ofrece un simple resaltado de sintaxis.

Los enlaces sólo son visibles para los usuarios registrados.

Los enlaces sólo son visibles para los usuarios registrados.

Así es como el conocimiento empresarial se hace tangible

La experiencia de sus propios empleados es un factor económico importante para cualquier organización. Por eso es tan importante almacenar permanentemente la experiencia y los conocimientos y ponerlos a disposición de los demás empleados. Un servidor central de gestión del conocimiento se encarga de esta tarea y contribuye a garantizar la productividad de la empresa a largo plazo.

(c) 2011 Marco Schulz, Materna Monitor, Ausgabe 2, S.32-33
Artículo original traducido del Deutsch

La complejidad del actual mundo laboral, altamente interconectado, requiere la interacción fluida de una gran variedad de especialistas. La transferencia de conocimientos desempeña aquí un papel importante. Este intercambio se hace más difícil cuando los miembros del equipo trabajan en distintos lugares con diferentes husos horarios o proceden de entornos culturales diferentes. Las empresas con sedes en todo el mundo conocen este problema y han desarrollado estrategias adecuadas para la gestión del conocimiento en toda la empresa. Para introducirla con éxito, la solución informática que se utilice debe considerarse como una metodología en lugar de centrarse en la herramienta en sí. Una vez tomada la decisión por una determinada solución informática, debe mantenerse de forma coherente. Los cambios frecuentes de sistema reducen la calidad de los vínculos entre los contenidos almacenados. Al no existir una norma normalizada para la representación de los conocimientos, pueden producirse importantes pérdidas de conversión al cambiar a nuevas soluciones informáticas.

Diferentes mecanismos para diferentes contenidos

La información puede almacenarse en los sistemas informáticos de diversas formas. Las distintas formas de representación difieren en su presentación, estructuración y uso. Para poder editar documentos sin conflictos y versionarlos al mismo tiempo, como es necesario para las especificaciones o la documentación, las wikis [1] son ideales, ya que se desarrollaron originalmente precisamente para este uso. Los documentos que allí se almacenan suelen ser específicos de cada proyecto y también deben organizarse de esta manera.

Los documentos transversales de la wiki son, por ejemplo, explicaciones de términos técnicos, una lista central de abreviaturas o un Quién es quién de los empleados de la empresa con datos de contacto y áreas temáticas. Estos últimos, a su vez, pueden enlazarse con la explicación del término técnico. De este modo, el contenido completo puede mantenerse actualizado de forma centralizada y vincularse cómodamente a los documentos de proyecto correspondientes. Este procedimiento evita repeticiones innecesarias y los documentos que hay que leer se hacen más cortos, pero siguen conteniendo toda la información necesaria. Johannes Siedersleben ya describió los riesgos de una documentación demasiado larga en su libro Softwaretechnik [2] en 2003.

Los conocimientos que tienen más carácter de FAQ se organizan mejor a través de un foro. La agrupación por temas, en los que se depositan preguntas del tipo “¿Cómo puedo…?”, facilita la búsqueda de posibles soluciones. Especialmente atractivo es el hecho de que un foro de este tipo evoluciona con el tiempo en función de la demanda. Los usuarios pueden formular sus propias preguntas y publicarlas en el foro. Por regla general, las respuestas cualificadas a las nuevas preguntas no tardan en llegar.

Los candidatos idóneos para los blogs son, por ejemplo, información general sobre la empresa, informes de situación o tutoriales. Se trata de documentos que tienen más carácter informativo, no están ligados a un formulario o son difíciles de asignar a un tema concreto. Las informaciones breves (tweets [3]) a través de Twitter, agrupadas temáticamente en canales, también pueden enriquecer el trabajo de los proyectos. Además, minimizan el número de correos electrónicos en la propia bandeja de entrada. Algunos ejemplos son recordatorios sobre un evento determinado, una noticia sobre nuevas versiones de un producto o información sobre un proceso de trabajo finalizado con éxito. La integración de los tweets en el trabajo de un proyecto es relativamente nueva y, por tanto, las soluciones de software adecuadas son escasas.

Por supuesto, la lista de posibilidades está lejos de agotarse en este punto. Sin embargo, los ejemplos ya ofrecen una buena visión de cómo las empresas pueden organizar sus conocimientos. Conectando los sistemas individuales a un portal [4] que disponga de una búsqueda global y una administración de usuarios, se crea rápidamente una red que también es adecuada como solución en la nube.

La facilidad de uso es un factor decisivo para la aceptación de una plataforma de conocimiento. Largos periodos de formación, una estructuración poco clara y un manejo engorroso pueden provocar rápidamente el rechazo. Con la autorización de acceso a los contenidos individuales a nivel de grupo, también se satisface la seguridad. Un buen ejemplo de ello es la wiki empresarial Confluence [5]. Permite asignar diferentes permisos de lectura y escritura a los niveles de documentos individuales.

Naturalmente, no se puede esperar que un desarrollador describa su trabajo con las palabras adecuadas para la posteridad después de haberlo aplicado con éxito. El hecho de que la calidad de los textos de muchas documentaciones no siempre es suficiente también ha sido reconocido por la Universidad de Ciencias Aplicadas de Merseburg, que ofrece el curso Edición técnica [6]. Por ello, la lectura cruzada por parte de otros miembros del proyecto ha demostrado ser un medio adecuado para garantizar la calidad del contenido. Para facilitar la redacción de los textos, resulta útil disponer de una pequeña guía, similar a la Convención de Codificación.

Conclusión

Una base de datos de conocimientos no puede implantarse de la noche a la mañana. Se necesita tiempo hasta que se ha recopilado suficiente información. Sólo mediante la interacción y la corrección de pasajes incomprensibles el conocimiento alcanza una calidad que invita a la transferencia. Hay que animar a cada empleado a enriquecer los textos existentes con nuevos conocimientos, a resolver pasajes incomprensibles o a añadir términos de búsqueda. Si el proceso de creación y distribución de conocimientos se vive de esta manera, quedarán menos documentos huérfanos y la información estará siempre actualizada.