El proceso de documentación surge evolutivamente de comentarios medios en el código a medida que una empresa crece. En algún lugar en el medio del camino, generalmente aparecen personas que dicen que saben cómo hacerlo bien y que "este libro dice cómo hacer la documentación", y que traen un proceso difícil a la empresa. Además, hay discusiones, disputas, enlaces a diferentes fuentes con enfoques conflictivos, etc. De hecho, todo esto no es accidental. Cada vez que nos encontramos con esos momentos, significa que hay diferencias culturales. Las tendencias están cambiando, y cada era ofrece sus propios libros de texto.
Debajo del corte, junto con Maxim Tsepkov entenderemos qué lecciones se pueden aprender de diferentes enfoques, cómo diseñar documentos de proyecto, qué poner en una wiki, para qué es adecuado Google Docs y qué debe estar siempre frente a sus ojos. De todos modos, ¿por qué necesitamos toda esta documentación? Al mismo tiempo, tocaremos el tema de la gestión del conocimiento.
Programas de proyectos culturales
La historia de la industria de TI se divide en etapas, cada una de las cuales tiene su propio enfoque para la gestión de proyectos: sus propias ideas sobre el éxito, los criterios de calidad y la organización del trabajo. Anthony Lauder en 2008 escribió el libro "Cultura de proyectos de software" (enlaces al
original ,
traducción y
revisión de Stas Fomin ), en el que identificó cuatro períodos:
- científico
- fábrica
- diseño;
- cultura de servicio.
Cada uno de ellos influyó en los enfoques para la gestión de proyectos de software. Y nadie pensó en la coherencia entre ellos.
Sobre el orador: Maxim Tsepkov, arquitecto de TI y analista de negocios, navegador y experto en el mundo de las organizaciones ágiles, turquesas y dinámicas en espiral.Utilizo una periodización ligeramente diferente, extendida hasta la fecha. En el esquema que propongo, lo principal que ha cambiado es el alcance del proyecto. En la era de I + D, era importante que el sistema de TI funcionara, en la era de RUP, que se hizo a tiempo, en la era de Agile, que hace lo que el cliente necesita y no solo funciona, porque resultó que a menudo hicieron lo incorrecto.
En los tiempos modernos, un proyecto de TI debe proporcionar una solución a los problemas comerciales y brindar satisfacción a las partes interesadas. No importa cuál de los esquemas de división cultural sea realmente correcto, cualquiera puede usarse, porque las diferencias están solo en los detalles.
Pero es importante comprender que la mayoría de los libros de texto sobre documentación se escribieron en la era RUP, en la que la organización del proceso tenía como objetivo cumplir con el presupuesto y los plazos. Esto no funcionó, pero los libros de texto permanecieron y
no escribieron nuevos libros de texto .
Ágil al comienzo de su desarrollo balanceó el péndulo en la dirección opuesta, anunciando que el software de trabajo es mucho más importante que los documentos. Y luego había formatos privados: historias de usuarios, casos de uso, prácticas privadas, mapeo de historias, etc., que se reflejaban en los documentos. Pero no escribieron libros de texto completos sobre este tema, porque entendieron que los libros de texto no funcionan.
Ahora nos dimos cuenta de que los
proyectos son diferentes y definitivamente no hay recetas universales : debemos hacer lo que sea apropiado. Pero no necesita inventar desde cero, necesita usar plantillas y muestras de la misma manera que sucede, por ejemplo, en el diseño de interfaces. Las interfaces son diferentes, especialmente en dispositivos móviles con una pantalla pequeña, debe colocar lo que ahora es importante para la tarea, no existen elementos universales. Pero
hay una guía de estilo que proporciona aprendizaje intuitivo, patrones y prácticas.
Al desarrollar una guía de estilo, se centran en UX. La documentación es la misma: en la guía de estilo Doc del proyecto.
Espero que el informe brinde principios y conceptos, en función de los cuales puede mejorar la situación y resolver problemas con los documentos de su proyecto.
Documentos - para comunicación
La idea principal, de la que procedo, es que los documentos no son valiosos, sino que proporcionan comunicación. Al igual que las interfaces en sí mismas, no importan, proporcionan al usuario la funcionalidad que está oculta en el lado del servidor.
La forma de los documentos, así como las interfaces, se desarrolla a partir de los objetivos de la comunicación.
Aquí es importante que en el caso de documentos a largo plazo, la comunicación se distribuya a lo largo del tiempo. Hoy te escribes una carta en el futuro, cuando será necesario volver a hacer cambios en la función que estás haciendo ahora. Volviendo a ella después de un año y medio, recuerda, descúbrelo. Puede ser un desarrollador o usuario completamente diferente que opere su sistema.
Y si el documento es necesario para la comunicación, entonces
debe ser dirigido . Con él, nos comunicamos con personas específicas y no enviamos a todo el mundo. Por lo tanto, dividimos los documentos por propósito y destinatario:
- para la toma de decisiones;
- comunicación actual;
- preservación del conocimiento a tiempo ("para mí en seis meses");
- transferencia de conocimiento a otras personas;
- ayuda en el trabajo actual, etc.
Cada destino tiene su propio tipo de descripción, - punto de vista -
su propio método de descripción .
Criterio de calidad del documento
El criterio de calidad será cómo el documento respalda la comunicación para la cual fue creado.
La claridad del documento para todas las partes en la comunicación es importante , lo que limita la complejidad de las anotaciones. Cuando presentamos diagramas de clase, procesos de negocio, estado del documento para el cliente, no debemos olvidar quién leerá los documentos.
Los diagramas de clases en UML son una construcción de notación muy complicada, que en una forma simple, cuando solo se dibujan clases y relaciones, es casi intuitiva. Pero luego, cuando el gráfico se carga con todo tipo de íconos adicionales, rápidamente se vuelve comprensible solo para el autor y los desarrolladores. Piensan que transmitieron los significados. Y el cliente piensa que los desarrolladores aquí tomaron algunas notas por sí mismos, lo cual no tiene sentido, pero no pueden borrarlas. Al mismo tiempo,
los esquemas simplificados deberían preservar los puntos clave . Vale la pena utilizar todo lo que se ha acumulado: hipertexto, enlaces, textos, gráficos, audio, video para que sea efectivo.
Los esquemas y modelos son mucho más efectivos que el texto , porque el lenguaje natural es ambiguo. La experiencia sugiere que los esquemas y las visualizaciones están mucho menos distorsionados y malinterpretados que el texto. Pero los esquemas deben ir acompañados de descripciones que, lo que es más importante, no duplican el contenido, sino que explican la esencia.
Es necesario crear un
diccionario de conceptos , un solo lenguaje de proyecto, pero es importante discutir no los términos, sino el contenido. No es necesario discutir cómo usar la palabra para algún concepto. Necesitamos discutir sobre qué conceptos y objetos tenemos en esta área temática y resaltarlos. Sobre el tema del pluralismo terminológico y los enfoques para trabajar con él, hay buenos fragmentos en el curso de las conferencias sobre pensamiento en ingeniería de sistemas de A. Levenchuk.
El siguiente punto importante a recordar al diseñar un sistema de documentación:
"por qué" y "por qué" son más importantes que "qué" . El caso de uso describe lo que se debe hacer en el sistema, y en la historia del usuario hay una parte del "por qué": "Como
<> Quiero
< -> para
< > ". Además, este formato de
historia de usuario puede considerarse como una plantilla, es decir, Todas las partes deben ser. No surgieron inmediatamente de la experiencia, pero ahora sabemos que "por qué" es muy importante. El objetivo de la historia del usuario, el objetivo de cualquier requisito es la comunicación distribuida en el tiempo del cliente (usuario) con el desarrollador y el analista como intermediario.
En esta comunicación distribuida en el tiempo, es muy importante transmitir los significados para que el desarrollador tome decisiones específicas. Siempre hay alternativas imprevistas: por la ubicación de los botones en el formulario, por código, por flexibilidad, por la generalidad de la solución. Si la decisión es crítica, el desarrollador, por supuesto, interrumpirá y aclarará. Pero es mejor que en ese momento él mismo pueda establecer la tarea comercial y tomar una decisión: la interrupción en el proceso de codificación es costosa. La respuesta a la pregunta "por qué" en la documentación ayuda mucho, por eso apareció.
La lección sobre "por qué" y "por qué" debe tenerse en cuenta, incluso si utiliza otros formatos, para fijar los objetivos de los usuarios y las empresas, comenzando por los objetivos del proyecto. Y luego, el contenido de los objetivos del proyecto a menudo se reduce a "el negocio por alguna razón es necesario".
No es necesario hacer ciegamente cosas extrañas que la empresa no entiende por qué querían. Por lo general, tiene motivos completamente racionales, después de desenterrar, lo que resulta que hay que hacer cosas completamente diferentes.
Diseñamos documentos de proyectos.
¿Cómo diseñar? Como cualquier otro sistema. Lo más importante que debes cambiar en ti mismo es que no necesitas tomar la plantilla terminada y copiarla, pero debes diseñar una nueva, cómo lo haces con las interfaces. Es necesario tomar y diseñar las interfaces de su sistema, confiando en toda la variedad.
A continuación, destacamos los casos de comunicaciones, determinamos los documentos que los respaldarán. Si la comunicación se distribuye a lo largo del tiempo, entonces necesita una persona responsable de mantener los documentos y la aceptación competente de los documentos. Porque, si después de 3 años encontramos que las descripciones, digamos, no son muy inteligibles, entonces esta retroalimentación será un poco tardía, no habrá nadie para transmitirla.
Además en el proceso de uso, evaluamos la calidad y la mejoramos de la misma manera que usabilidad y UX.
Para diseñar, necesitas circuitos. Un esquema conveniente es el
modelo V , que muestra la cadena del proyecto como un ejemplo de abstracción y luego entrega el resultado.
Si en este modelo colocamos los artefactos clásicos de interacción entre el cliente y el equipo, entonces habrá: requisitos, tarea de desarrollo, casos de prueba,
PMI , versiones. Los artefactos tendrán algún tipo de retraso responsable.
No es el hecho de que necesite estos documentos. Esto se aplica especialmente a los requisitos y tareas de desarrollo.
Existe, por ejemplo, una alternativa: el diseño impulsado por dominio, según el cual, en lugar de requisitos y tareas de desarrollo, se utiliza un modelo de sistema como un artefacto colectivo. El modelo refleja el sistema, y lo llevan a cabo analistas por un lado y desarrolladores por el otro.
Hay muchas opciones y prácticas de este tipo. Todos ellos están estrechamente relacionados con el proceso de desarrollo, porque es en el proceso que surgen las comunicaciones. Mire su proceso y haga artefactos adecuados para él.
El modelo V es un legado de las épocas de I + D y RUP. Desde entonces, las culturas han cambiado y el diseño moderno es mucho más amplio. En lugar del concepto, surgieron cosas como las necesidades del usuario y las oportunidades comerciales. A la derecha, en lugar de un mantenimiento único, hubo una entrega de la próxima versión y soporte continuo a tiempo.
Requisitos
Por lo general, existe un artefacto clave entre el concepto y el inicio del proyecto: el
concepto o Visión , que captura la posición inicial del proyecto. Nos correlacionaremos con el concepto a medida que se desarrolle el proyecto, pero lo más importante, es sobre la base de que se toma una decisión desde el principio, ya sea asumir el proyecto o no.
La cantidad de concepto o visión que debe elaborarse en detalle se determina funcionalmente: el documento debe hacerse lo más breve posible, porque es rápido, pero para que las partes interesadas tomen una decisión sobre el inicio del proyecto. Por lo general, el concepto debe reflejar:
- idea de proyecto: una oportunidad de negocio: qué, para quién y cómo hacer;
- la viabilidad y la viabilidad de la idea;
- intereses y expectativas de los principales interesados del resultado del proyecto;
- diseño del producto y uso previsto;
- evaluación de los recursos necesarios para el proyecto.
Además, los intereses y las expectativas pueden cambiar, y si esto sucede, es importante arreglarlo a tiempo.
En el proceso de trabajar en los requisitos, es importante el
límite externo del proyecto . Con el cambio de culturas, las ideas al respecto cambiaron de características como parte del diseño del sistema (en la era de I + D) a características en función de un sistema que hace algo dentro de sí mismo, y ahora la característica es un valor para los usuarios. Estos son diferentes niveles de artefactos; diferentes especializaciones son responsables de ellos: arquitecto, analista de sistemas, analista de negocios. Pero este es un enfoque funcional del sistema.
Si hablamos de la satisfacción del usuario, también apareció una línea de especializaciones: un diseñador de interfaz de usuario que es responsable de la satisfacción del usuario con la apariencia, usabilidad - sobre el uso y un especialista en UX que trabaja en la capacidad de interfaz intuitiva. Esta frontera también está cambiando. En su proyecto específico, puede ser diferente, ya que el desarrollo empresarial es una cosa, para lo cual existe un sistema de capacitación, y el usuario no irá a ningún lado como un contador 1C, porque este es su lugar de trabajo. Y otra cuestión, por ejemplo, el desarrollo móvil. Si la rotación del personal de la tienda es tal que el vendedor o el empleado de la tienda trabajan en promedio durante 3-6 meses, entonces la cuestión de desarrollar una aplicación móvil para trabajar en 2 días, y no en 2 semanas de capacitación, es relevante.
El mantenimiento de los requisitos debe ser coherente con el enfoque de prueba y viceversa. Si tiene los requisitos clásicos de Requisitos y Arquitectura, entonces es posible el Diseño Dirigido por Prueba, y el Diseño Dirigido por Comportamiento es poco probable. Debido a que BDD está diseñado para garantizar que formule un escenario para los usuarios, es decir, a un mayor nivel de abstracción. Si no hay un escenario en los requisitos, entonces no hay lugar desde donde tomarlo. Tales relaciones deben tenerse en cuenta, y el
costo de mantener y verificar los casos de prueba también debe
controlarse .
Artefactos de enfoque personalizados
Una clase separada de artefactos diseñados para el enfoque individual diario. Estos son, por ejemplo, aquellos circuitos que se
imprimen y cuelgan frente a la sala de desarrolladores . Una de las lecciones de Agile: un
tablero de tareas y un cuadro de Quemado , físicamente colgado en una habitación o configurado con teclas de acceso rápido en formato electrónico, son muy útiles. Una mirada distraída en el pensamiento, se aferra accidentalmente, y la información se actualiza constantemente. Del mismo modo, con esquemas arquitectónicos, principios importantes.
Es cierto que si cuelgas todo lo recomendado en las paredes, quedarán tan colgados que el significado de enfocarte en el documento antes de que tus ojos se pierdan, en la masa se perciben como papel tapiz. En este sentido, la pregunta "¿qué colgar en las paredes, qué artefactos siempre estarán frente a tus ojos?" También es un problema de diseño que debe abordarse. Obviamente, exactamente lo que es importante debe colgar.
Los diagramas ER, un diagrama en capas de la aplicación o los componentes principales se encuentran en la documentación. Pero mentir en la documentación o colgar en la pared todo el tiempo es una gran diferencia. Cuando un desarrollador piensa: "¿Pero no cavar un agujero en la API en la parte superior del modelo en capas oblicuamente?", Porque realmente reducirá el tiempo de desarrollo de una característica específica (pero luego aparece con el acompañamiento), y mientras tanto el esquema cuelga ante sus ojos, lo más probable es que vea que será un hoyo Si el diagrama está en algún lugar del documento, puede olvidarse temporalmente de él y escribir rápidamente código que viole la arquitectura.
Project Motion Knowledge
En el proceso Scrum hay puntos especiales para generar conocimiento sobre el movimiento del proyecto:
- Demostración: presentación del estado del proyecto a quienes utilizan los resultados de su trabajo y a otras personas interesadas.
- Retro es una autoevaluación: si trabajamos correctamente y qué se puede mejorar.
- Reunión diaria: sincronización de las ideas del equipo sobre el movimiento del proyecto.
- Planificación - sincronización de intenciones.
Es importante que estas reuniones de comunicación estén espaciadas y enfocadas cada una en su propio objetivo. Además, se desarrollan formatos para ellos. Hay libros completos sobre cómo realizar retrospectivas y qué artefactos deben acompañar. Además, algunos artefactos, como el código, son de extremo a extremo, porque las tareas que deben planificarse juntas provienen de retro. En consecuencia, las retrospectivas de la tarea se suman al trabajo atrasado, pero están marcadas, por ejemplo, con color. Trabajamos con uno u otro, esto es normal.
Descripciones a largo plazo
Al crear descripciones a largo plazo, la pregunta principal es determinar
qué casos admitirá la descripción . Las opciones pueden ser completamente diferentes:
- Enseñe a un nuevo usuario a trabajar con el sistema.
- Proporcione información de referencia sobre las funciones raras del sistema.
- Presente el diseño conceptual del sistema a un nuevo desarrollador.
- Para ayudar a recordar el fragmento del dispositivo del sistema al autor para mejoras.
- Describa el sistema de módulos del dispositivo para el desarrollo de un nuevo desarrollador.
- Proporcione información sobre el dispositivo del sistema al ingeniero de soporte.
En este sentido, primero formula la tarea que necesita respaldar, luego crea documentos con el nivel de detalle necesario, etc.
La descripción universal es detallada, costosa, irrelevante y también innecesaria, porque no puede encontrar la información necesaria en ella debido a sus detalles.
Es necesario
fijar el propósito , evaluar el cumplimiento, recordar: cuanto más detallado sea el documento, más costoso.
Una pregunta típica: ¿las actas de las pequeñas reuniones periódicas con el cliente deben ser claras y recordar el contenido de la discusión solo para aquellos que participaron en la reunión, o ser tales que puedan enviarse a todos los que no participaron en la reunión, y también podrían resolverlo? Este es un tema importante.
Obviamente,
los protocolos más
detallados son mucho más caros . Esto debe ser administrado, y las compensaciones pueden ser aplicables. Por ejemplo, ingrese un breve resumen en el protocolo y consulte el video o audio grabado para obtener más detalles. Realmente puede ser útil, muchos regresan a las grabaciones de video.
Al mismo tiempo, volviendo al "por qué y para qué", no nos olvidamos de fijar la lógica de las decisiones en el resumen, y no solo "qué hacer". Brevemente, pero es importante.
Con los documentos normativos necesarios de acuerdo con GOST, debe comprender si son necesarios para la entrega del proyecto o para otra cosa. Como norma, los documentos normativos aseguran la comunicación del cliente con sus inspectores y deben escribirse en el volumen en que sea necesario, y teniendo en cuenta el uso por parte del cliente. A veces estos son documentos de solo escritura. Por ejemplo, tenemos clientes para quienes la documentación de trabajo y la documentación para los inspectores se producen por separado. Pero hay quienes quieren que los documentos que se examinen funcionen, básicos. Dependiendo de esto, el proceso de documentación es diferente, pero tan pronto como comprendamos su propósito, todo estará bien.
La comunicación transmite significados
Divaguemos un poco y discutamos que la comunicación transmite significado.
Todo comienza con la suposición de la era RUP, que generó el Enfoque Orientado a Objetos (OOP). Si descomponemos el mundo en
objetos y conexiones , obtenemos una imagen inequívocamente interpretada del mundo.
El cliente puede ver el mundo como una colección de agentes interactivos en el modelo de Haskell que intercambian mensajes. Los agentes son iguales y las palabras son claras, pero la imagen es completamente diferente. El esquema, a diferencia del texto, refleja esta diferencia. Por lo tanto, usamos el esquema.
Una forma diferente de pensar es la norma . Modelos jerárquicos, las taxonomías pasaron del desarrollo científico del mundo, en el que todo se reduce a una forma estricta y "se coloca en los estantes". Ahora, con el desarrollo de Internet, el pensamiento del mundo es popular como una
nube de etiquetas con conexiones, incluso hay una palabra especial:
"folksonomía" . Tal pensamiento es eficiente y operable. Marketing, los medios se basan en esto. Y el mundo de los ingenieros de TI, que están más cerca de la imagen científica del mundo, se enfrenta cada vez más a esto.
En este sentido, necesita
saber y corregir la diferencia en el pensamiento . De lo contrario, creará un sistema cuadrado y el cliente preparará un agujero redondo para él. Entonces comenzará el proceso de combinación y tendrá que contentarse con un poco de krakozyabra en forma de lágrima, porque una esquina de su patrón cuadrado no se puede cortar, está hecha de metal arquitectónico sólido.
Qué hacer es comprensible.
Dibuja los diagramas . Debemos tomar fuentes ya conocidas y conocidas, por ejemplo, UML. Pero tenga en cuenta que las anotaciones formales no son bien entendidas por todos, y muchos perciben esquemas incompletos e informales exclusivamente como imágenes.
La fuente ortogonal de esquemas fuera de TI es la metodología SMD (ver el informe
"Comunicación con una estructura de pensamiento diferente: taxonomía versus folksonomía" ).
Principios de gestión documental
1. El documento no tiene autor.Vive más tiempo que el primer autor, por lo que trabajamos colectivamente, y
no reenviamos en letras , utilizamos sistemas wiki. También puede Google Docs, pero hay documentos separados, lo que no siempre es conveniente. Para producciones de corta duración, Google Docs es excelente.
Una consecuencia importante se desprende del principio de que un documento no tiene un autor y experiencia en sistemas wiki: vi qué mejorar, hacerlo de inmediato, la coordinación solo es necesaria por desacuerdo.
Parece que todos entienden que no hay autor, pero pocos corrigen el documento de otra persona. La ortografía todavía está bien, pero si algo es más complicado, entonces el autor debe ir y escribir. No,
debes tomarlo y arreglarlo . Todos los sistemas wiki tienen notificaciones. Si el autor está interesado en el documento, verá un aviso, mirará el historial de cambios y explicará si está equivocado. Pero en la mayoría de los casos, él no se dará cuenta o decidirá qué se arregla normalmente. El éxito de Wikipedia es solo eso.
2. El documento se crea gradualmente.Un documento grande se vuelve obsoleto antes de ser escrito. Baste con conceptos concisos, y detalle según sea necesario. Hacemos la parte del documento que se relaciona con la tarea actual.
Los formatos que trajo Agile: historia de usuario, caso de uso, mapeo de historia, a diferencia de las producciones monolíticas anteriores, no aparecieron de inmediato. Se centran precisamente en la creación incremental de documentos, elaboración incremental. No están en todas partes, pero tan pronto como decidimos enviar y detallar los documentos de forma incremental, esto impone las mismas restricciones en la estructura de los artefactos que en el código. Tan pronto como escribamos el sistema de forma incremental, y no lo depuremos por completo, debemos organizar el código en consecuencia: arquitectura de componentes, arquitectura de microservicios: hay muchas opciones, pero no un monolito.
3. El contenido es más importante que la forma.Los requisitos formales del documento no funcionan. Se pueden tomar para ahorrar tiempo al principio, pero este no es un criterio de calidad. Los criterios para la idoneidad de los documentos de uso de las partes interesadas funcionan: listas de verificación y evaluación de expertos.
En este punto, las regulaciones no funcionan: esta es una lección sobre el desarrollo de la industria de TI y no de la industria de TI. Cualquiera puede editar en sistemas Wiki, no hay un largo proceso de aprobación, etc. Lo mismo con las políticas de compromiso en muchos proyectos OpenSource. Por supuesto, hay aprobación, etc., pero es una experiencia materializada que debe usarse.
4. Dejamos huellas.Este otro principio importante se refiere a actas de reuniones, resúmenes de conversaciones. Es decir, hablamos en vivo, chateamos y escribimos un resumen de 1-2 oraciones en Task Tracker. , , -, , .
. , , ,
. . , , . - , . , .
— , , .. , - , -, , , , . : , .
:
- Archimate.
- Archimate.
- - , Domain Driven Design.
- OMG Essence.
- viewpoint' ISO 42010.
. , , .
, , . , , , , , , , , : , .
, Wiki — , , , , , .. , - . CUSTIS MediaWiki. , Jira Confluence, OpenSource http://4intra.net. , , wiki- , .
— . Slack, Task Tracker Google Docs, .
. , wiki. wiki git, - wiki- , .
— , .
, , .
,
« » . , : « , ?» , . , , « » , British Petroleum. , , , .
. .
, .
, , 5–7 , . .
, , , C# , . .
—
. — , wiki — , . . , , , . , , .
— , . BBC , , , . , , . , , .
IBM: — .
IBM : , - , . , . IBM , . , , , , , , , « , , ». . — , , .
mtsepkov.org (, , wiki)
,
agile ,
.
— . , : , , , , Knowledge Conf .
25 TeamLead Conf . , .