Aunque la segunda reunión de Write the Docs Moscow tuvo lugar hace un mes, nunca es demasiado tarde para publicar un informe y resúmenes breves de informes. Pudimos discutir bien prácticamente todo: desde documentar una API RESTful hasta trayectorias profesionales de un escritor técnico.
Mitap, por cierto, reunió no solo al "gueto técnico", sino también a una amplia gama de otros especialistas que trabajan de una forma u otra con la documentación del proyecto: líderes de equipo, analistas, evaluadores e incluso un director técnico.
Nuestra
reunión tuvo lugar el 14 de octubre , domingo (entró en la parte superior de las preguntas más populares sobre él, "¿Por qué el domingo?") En la oficina de IPONWEB. Las manifestaciones de Write the Docs se llevan a cabo en todo el mundo desde Bangalore a San Francisco, desde Londres a Seúl, la rama rusa de la comunidad solo está ganando actividad, pero ya hay sucursales en Moscú, San Petersburgo y Novosibirsk.
Anton Telin, ¿Por qué y cómo hacemos las instrucciones en video?VideoDiapositivasAnton gestiona el departamento de documentación técnica de VLSI, que crea un sistema de gestión de documentos electrónicos. ¿Por qué un video? Las personas no quieren leer instrucciones, quieren resolver un problema. La gente quiere que se les explique clara y claramente.
El video es una forma conveniente de presentar una gran cantidad de información, implementar un script en dinámica, una secuencia de acciones. También puede acentuar la atención del usuario con música o doblaje.
Si el producto es complejo y no tiene una interfaz bien pensada, entonces, sin la parte visual, es difícil transmitir su esencia al usuario. La ventaja es que reduce el costo del soporte técnico.
Contras: no es adecuado para todos los formatos de publicación, es difícil de integrar en doc y pdf. Es difícil buscarlo. Los videos de alta calidad son más caros.
Otro problema urgente es la complejidad de la actualización, pero la campaña de Anton resolvió este problema. Se negaron a grabar screencasts (capturas de pantalla) a favor de capturas de pantalla de alta calidad.
La compañía usa dos formatos de video:
1. La instrucción en video es una secuencia de acciones, en detalle y en pasos. Duración ~ 2 minutos. 1 instrucción es 1 problema. No habla de todas las ventanas, grajillas, botones. Luego se agregó doblaje, música de fondo, explicaciones de texto, subtítulos.
2. Video explicativo. Esto es algo en la unión de la instrucción y presentación del producto. Una vista general sin detalles técnicos resuelve varios problemas o escenarios. Este video puede incluir personas y animación. Duración 2-3 minutos.
Herramientas: Adobe Premiere y Adobe After Effect para editar, Adobe Audition para sonido, Photoshop y Snagit para editar imágenes. El proyecto se ensambla a partir de una variedad de capturas de pantalla, que no son relevantes o erróneas, por lo que es fácil de reemplazar. A continuación, dibujando el movimiento del mouse, animación, sonido.
Decidieron usar locutores no profesionales para el doblaje, ya que sonaban demasiado formales, por lo que usan la voz de un empleado de la compañía, Ilya, que canta en un grupo de metalcore. Después de un bloque de información, se da necesariamente una pausa de 2 segundos para la comprensión.
Los videos se publican tanto en su propio alojamiento como en Youtube. La desventaja es que muchas compañías lo bloquean por razones de seguridad.
Por supuesto, VLSI recopila todas las estadísticas disponibles: tiempo promedio de visualización, me gusta, llamadas de soporte técnico que se cerraron mediante el enlace de video.
Nikolay Volynkin, escritor técnico versión 2.0.1VideoDiapositivasEsta es una repetición, o mejor dicho, una adición al informe de la conferencia SECR. Nikolai observó a los escritores técnicos durante mucho tiempo y notó que no siempre saben cómo justificar y medir sus beneficios, y también a los líderes que les asignaron tareas.
Hay algunas tareas relacionadas que los escritores técnicos podrían resolver. Nikolay dijo qué trayectorias profesionales y conjuntos de habilidades tienen descripciones técnicas, cómo vender sus nuevas tareas a la empresa.
5 roles que puede desempeñar un escritor técnico:
1.
Docops : devops para documentación, un escritor / programador, puede automatizar la generación, verificación, carga de documentación, capacita al equipo para trabajar con ella y reconstruye todos los procesos a su alrededor.
Los beneficios son mano de obra reducida, ahorro de recursos y mayor velocidad de entrega de funciones.
2.
Escritor UX : especialista en escribir textos en interfaces.
Beneficios: los diseñadores, poemas, analistas o desarrolladores front-end no siempre entienden cómo escribir correctamente, cómo transmitir funciones, botones, transiciones a un usuario. Los textos se escriben de acuerdo con el principio de quién se levantó primero y las zapatillas. Conveniencia de la interfaz, lo que reduce el tiempo de soporte técnico.
3. Un
evangelista técnico , habla sobre tecnología, interactúa con la comunidad, le da forma.
Beneficios: mayor confianza y lealtad a la empresa, al producto, simplificación de la contratación, marca de recursos humanos.
4.
Knowledge Manager : explora cómo una empresa produce, almacena y transfiere conocimiento. Establece estos procesos para que el conocimiento no se filtre.
Beneficios: factor de autobús reducido, la velocidad de adaptación de los empleados, tanto principiantes como durante las transiciones internas, reutilización de conocimientos, reducción de riesgos.
5.
Propietario de la documentación - PM y analista de documentación. Construye todo el sistema de comunicación e interacción del usuario en la documentación.
El beneficio está nuevamente en la reducción de los costos de soporte.
Durante la discusión, recordamos una función tan integrada como administrador de contenido, que no se mencionó en el informe.
Konstantin Valeev, FoliantVideoDiapositivasConstantine de Restrim habló sobre la herramienta Foliant: la implementación del flujo de trabajo de docops basado en el lenguaje Markdown. Hace un año, como parte del
mini-Hyperbaton en Yandex, Konstantin ya habló sobre Foliant, y mucho ha cambiado desde entonces.
La documentación está escrita en archivos MD y, en diferentes lugares, la herramienta admite la integración continua, el ensamblaje automático y también le permite expandir MD a su gusto.
Requisitos: debe proporcionar docx para clientes y PDF con buena tipografía, tener fuentes legibles por humanos (no XML).
Debajo del capó, se usa un convertidor Pandoc universal, Python, los scripts de bash están enrollados en la parte superior. Pero con el tiempo, el número de guiones creció, por lo que se reescribieron en una sola aplicación monolítica.
Desde el monolito, hicieron una estructura modular con el núcleo controlando el ensamblaje, preprocesadores que convierten el MD para el trabajo de los ensambladores y los ensambladores mismos.
Foliant es esencialmente el pegamento entre buenas herramientas (mkdoc, pandoc, pizarra, látex). Ahora están tratando de enseñar cómo consumir fuentes de documentación de diferentes formatos.
En la carpeta del proyecto hay una configuración con la estructura del documento final, los estilos y los archivos MD reales, luego los preprocesadores toman los archivos MD de origen y les aplican el procesamiento para hacer el MD deseado en el estilo de all.md (md en el estilo de foliant), luego los recolectores de los documentos finales ( pandoc, mkdoc) los convierten en objetivos (documentos). Después del ensamblaje de MD, se ejecutan linters para verificar la sintaxis. También se envían notificaciones de compilación sobre compilaciones o errores.
Todo esto se puede recopilar en Docker, de modo que todos los paquetes se entreguen de una manera, y no cada uno por separado.
Foliant admite la inclusión avanzada, puede extraer fragmentos de código de Gitlab / Github e imágenes con diseños de Simpli, puede dibujar diagramas, sustituir parámetros en el texto, declaraciones condicionales.
Nikita Samokhvalov, documentación completa sobre la API RESTfulVideoDiapositivasNikita Samokhvalov, Director Técnico de Notamed, contó cómo configuraron la generación de documentación API basada en Open API 3.0.
Como todos los demás, comenzaron con Google Docs, pero no tiene versiones ni la capacidad de crear sucursales. Luego, comenzaron a escribir archivos MD en el repositorio, el problema de versionar y crear ramas se resolvió, pero todo fue lento. Luego llegó a la autogeneración.
La documentación tenía los siguientes requisitos: herencia y reutilización de piezas de documentación, la capacidad de proporcionar un enlace a descripciones de parámetros y métodos, información sobre la diferenciación de derechos de acceso, documentación como un código (implementaciones y cambios sincrónicos). Además, la documentación no se publica públicamente, solo para su equipo y equipos de desarrollo de posgrado.
Elegimos la especificación OpenAPI 3.0. Por qué Es el más nuevo, admite más funciones, aunque todavía hay un pequeño ecosistema y experiencia a su alrededor.
Tomaron la herramienta
shins (muestra archivos MD en una hermosa página de inicio con ejemplos de consultas, descripción de métodos, parámetros),
widdershins (convertidor de yaml / json a MD), también escribieron su propio paquete
specker (instala todas las dependencias necesarias, funciona a través de npm, también verifica la corrección de la estructura de asignación de archivos).
La configuración del entorno y el montaje de la documentación se realizan en una sola línea en la consola. Los archivos que deben reutilizarse en cada proyecto, por ejemplo, una descripción de autorización, se incluyen en la carpeta / dependencias.
Nikita también habló sobre cómo trabajan con sucursales en un equipo distribuido, cuando la tarea es actualizar la documentación y, por supuesto, sobre las dificultades y dificultades que acompañaron la implementación de OpenAPI 3.0.
Svetlana Novikova, Gestión del conocimiento utilizando la matriz de competenciasVideoDiapositivasSvetlana (por cierto, este soy yo) habló sobre cómo en la empresa organizaron un reinicio del instrumento de extremo a extremo desde la esfera de gestión de personal como una matriz de competencia, cuál es el uso de la gestión del conocimiento de esta manera, cómo ayuda el instrumento a reducir el factor del autobús, es mejor abordar a los recién llegados, incluso encontrar piezas código para refactorizar.
Danila Medvedev, NeuroCodeVideoDanila habló sobre una herramienta que es comprensible para todos, y tal vez antes de nuestro tiempo, para modelar y almacenar conocimiento llamado NeuroCode.
Esta herramienta es útil para cualquier persona involucrada en el diseño de sistemas de TI. En particular, Danila sugiere abandonar los sistemas basados en documentos. Cualquier sistema se considera como una red, de acuerdo con los nodos de los cuales se transmite alguna información. Todos los elementos del sistema obedecen este principio: actualizaciones automáticas, transferencia de documentos, transferencia de comentarios. El propósito del NeuroCode es "reducir los costos improductivos para apoyar procesos y fortalecer la inteligencia colectiva de la organización".
El proyecto NeuroCode surgió de la solución del problema: cómo crear un buen depósito de información para un equipo o para usted mismo, cómo crear un modelo de información. El prototipo del sistema está hecho y funciona, ahora se está probando con la ayuda de ingenieros de sistemas y arquitectos comerciales. El sistema tiene una interfaz escalable y se basa en una estructura de datos fractales. También se basa en las ideas de Douglas Engelbart (este es uno de los primeros investigadores en la interfaz hombre-máquina, el autor de los conceptos de GUI, hipertexto, etc.) de la década de 1960 sobre Open Hyper-Document Systems (OHS), cuando el sistema no está basado en documentos, sino solo es decir, implementa todos los procesos de la actividad humana.
PD: en general, mejor mira el video.
La próxima reunión,
Write the Docs Moscow, tendrá lugar el 7 de diciembre en la oficina de Positive Technologies, y se llevará a cabo en el formato de Positive Authoring Tools Battle.
