Por lo general, hay un problema con la base de conocimiento corporativo para desarrolladores: se convierte en un vacío, porque no hay motivación para llenarlo con una persona responsable o un balcón lleno de cosas de un departamento soviético, todos contribuyen, pero escriben al azar, la información se vuelve obsoleta rápidamente y No siempre tiene tiempo para actualizar.
¿Cómo evitar esto, o al menos reducir los posibles costos? ¿Cómo hacer que su base corporativa sea cálida y con lámpara? Intentaré responder
Documentación de estilo de colaboración
Existe tal enfoque, documentación colaborativa, que apareció originalmente en el campo de la medicina, cuando la decisión de hacer un diagnóstico la toman colectivamente el paciente y varios médicos.
Un ejemplo sorprendente en el campo de TI es Google Docs, Wiki, Github, cualquier sistema que tenga convenciones internas y la capacidad de trabajar juntos en un proyecto.
La idea es incluir desarrolladores, expertos, críticos en el trabajo de documentación lo antes posible, para identificar las brechas juntas.
¿Por qué es esto necesario?
Primero, reducir el factor bus es un cuello de botella en el conocimiento corporativo, donde el número de poseedores de conocimiento tiende a la unidad. Debe transferir dicho conocimiento del jefe del desarrollador, desde pizarras, tickets, conversaciones en la cocina a un solo espacio para que todos puedan trabajar con ellos y contribuir.
En segundo lugar, para simplificar la entrada de los recién llegados a los proyectos, lo cual es especialmente importante para equipos distribuidos y equipos con un cierto número de desarrolladores de outsourcing, así como para aquellas empresas que tienen un área comercial muy específica, la posibilidad de encontrar un especialista listo es cero.
En tercer lugar, para la formación de una cultura corporativa sólida, transparencia "no en palabras". Un desarrollador en ese entorno comprende claramente los puntos de crecimiento profesional, qué otras tecnologías puede probar en la empresa, qué aprender.
Que hacer
Cualquier miembro del equipo puede redactar la documentación dentro de la base de conocimiento corporativo, esta oportunidad debe simplificarse para ellos, luego sentirán que son los dueños del resultado involucrado.
Sin embargo, definitivamente necesita una persona que asuma las funciones de un arquitecto de información: establezca reglas uniformes, estructura, lógica, estilo, coloque los documentos en espacios correctamente.
Abra la posibilidad de editar y crear documentos para los miembros del equipo, habiendo acordado previamente las reglas del juego. Automatice al máximo estas reglas: no confíe en el equipo, cree plantillas, etiquete el contenido automáticamente con etiquetas, configure la carga desde el repositorio a la base de conocimiento (por cierto, quiero hacer un artículo separado sobre esto).
Es importante que los desarrolladores vean que los documentos no desaparecen en el Wiki corporativo.
Un principio importante: la definición de hecho de un documento interno, este es el momento en que se hicieron enmiendas o comentarios , es decir, el momento de la colaboración. Este es su valor, quieren pasar tiempo en ello. No complemente, significa que el proceso de entrega, la implementación de la búsqueda está mal organizada o la herramienta es inconveniente.
Los problemas potenciales de este enfoque es la acumulación de ediciones y comentarios como una bola de nieve, es difícil hacer un seguimiento, a menudo se crean documentos duplicados.
Para evitar que esto suceda, puede y debe: A. Establecer el equipo en un vector, un conjunto de reglas y complicar el proceso de no seguirlas (por ejemplo, ocultamos el botón Crear en Confluence y hacemos que la selección de la plantilla sea obligatoria). B. Delimitar sabiamente los derechos y configurar los procesos de edición convenientemente para los responsables de la arquitectura de la información.
Y entonces vendrá el mundo perfecto
Los desarrolladores no dejarán de hacerse preguntas, incluidas las estúpidas y repetitivas . No aprenderán a encontrar todas las respuestas en la base de conocimiento por su cuenta. Tenemos humor interno cuando, debido a las limitaciones del índice de búsqueda Confluence, los desarrolladores no pueden encontrar algo, me preguntan como arquitecto de información. Lo llamamos búsqueda basada en Sveta.
A pesar de estas limitaciones, la estructura de la base de conocimiento en sí misma, el nombramiento unificado de páginas, el uso de etiquetas los estimulará a buscar y crear conocimiento para que, por ejemplo, no respondan preguntas que se repiten constantemente.
Otro truco de vida que aplicamos es incluir siempre un contexto comercial en los documentos, incluso si se trata de una descripción de una biblioteca o clase o una lista de verificación para una tarea, es importante comprender lo que esto significa para el cliente.
Ahora a practicar
La siguiente parte será sobre "Cómo", qué características internas de Confluence (sí, usamos la pila Atlassian) se pueden usar para implementar estos principios.
Patrones
Hemos creado plantillas listas para usar para los diferentes tipos de documentos que escribimos con mayor frecuencia: especificaciones técnicas, instrucciones, lista de verificación. Se pueden configurar en el panel de espacio de administración. Se necesitan plantillas para que al crear un documento el desarrollador no vea una página en blanco frente a él, ya tenga instrucciones sobre qué escribir en esta o aquella sección. Si desea que los documentos de un tipo determinado caigan en una sección y se muestra metainformación en ellos (esto es conveniente, por ejemplo, para describir los componentes de un producto complejo o un conjunto de microservicios de acuerdo con un esquema), luego cree un plano, esto es como una plantilla a la máxima velocidad.
En ellos configuramos el diseño de la página, los encabezados, donde solo queda reemplazar algunas palabras, un encabezado con un estado, imágenes, tablas, bloques de código e incluso variables.
Las variables son elementos de contenido preconfigurados a los que un editor de documentos adicional debe otorgar importancia, por ejemplo, ingresar texto o seleccionar de una lista.
También puede agregar etiquetas a la plantilla de antemano, si es un tipo estrecho del documento, puede mencionar a los usuarios como revisores, por ejemplo, si hay un flujo de trabajo claro por nombre, macro de Jira, y adjuntar un ticket de Jira. Nuestra experiencia muestra que hasta el 80 por ciento de las tareas se pueden cubrir con plantillas.
Diseño de página
Otro elemento importante es la creación de una página de aterrizaje comprensible y hermosa en el espacio del equipo. Para hacer esto, utilizamos el diseño de página y las macros Panel, Columna y Sección.
A continuación se muestra un ejemplo de uno de los espacios de nuestro equipo de desarrollo.
Use nombres de página amigables. Como ya sabrá, Confluence no admite nombres de página idénticos dentro del mismo espacio. Mantenga nombres de página claros, como
Mal nombre Python
Buen nombre Python Styleguide para el equipo de servicios internos
Etiquetas
La confluencia tiene algunas limitaciones para el algoritmo de búsqueda relacionado con la indexación de contenido. Y para la base de conocimiento corporativo, los problemas más apremiantes son precisamente la búsqueda y la conexión. Tenemos un artículo completo en la base de conocimiento llamado Cómo superar la búsqueda de confluencia, si lo desea, lo compartiré en los comentarios.
Para superar estas limitaciones, utilizamos un sistema de etiquetas. De hecho, se trata de etiquetas que marcan el tema del contenido y por qué le permiten agregar contenido de un tema en particular en un lugar en forma de una fuente de RSS (contenido macro por etiqueta). Así que hemos configurado índices de materias.
Si ya tiene cientos de páginas en la base de datos, le aconsejo que comience con los siguientes ejercicios:
- Vea una lista de todas las etiquetas en la siguiente URL https: // <my-host-name> /labels/listlabels-alphaview.action.
- Encuentre todo el contenido no etiquetado con ninguna etiqueta en la cadena de búsqueda avanzada: tipo: página NO labelText: [a TO z] NOT labelText: [0 TO 9].
¿Qué puedes ir y hacer ahora mismo?
- Otorgue a los desarrolladores el derecho de editar, pero sabiamente.
- Piense en la estructura del espacio de comando, haga una página de aterrizaje conveniente.
- Personaliza las plantillas.
- Usa etiquetas.
- Vaya y edite el documento de otra persona o escriba un comentario, haga que este documento funcione.