Ahora un zapatero con botas, o cómo obtuvimos nuestra propia guía de estilo

Supongo que, queridos lectores, en su trabajo han tenido que lidiar con documentación técnica y, posiblemente, incluso con quienes la crean, con escritores técnicos. Y en nuestro blog podrías conocer a un escritor técnico del equipo de Veeam.

Hoy pasamos al siguiente nivel de comprensión de cómo funciona el desarrollo de la documentación técnica en Veeam Software.

KDPV es engañoso: esto no es un milagro, sino el mismo trabajo que todos los demás colegas de I + D. ¡Sin embargo, aquellos que crean guías tienen palabras mágicas para sus guías en la creación de guías! Aquí hay tal recursión.

Lea más en la historia de mi colega Daria Shalygin.

Hola, mi nombre es Dasha y soy líder de calidad de contenido en Veeam Software. Soy responsable de la calidad del contenido creado por el departamento de redactores técnicos de nuestra empresa. En la práctica, soy escritor técnico y editor en una botella. Mis responsabilidades incluyen:

• ejecutar mis propios proyectos: como todos los escritores técnicos, tengo mi área de responsabilidad, es decir, una serie de productos para los que creo y mantengo documentación;
• Capacitación del personal de nivel junior: creé un curso introductorio para principiantes, que enseño para explicar las reglas básicas para escribir documentación;
• asesorar a los empleados de niveles superiores (experimentados y superiores): tengo sesiones diarias programadas durante las cuales cualquier miembro de nuestro equipo puede hacerme cualquier pregunta con respecto a la documentación (ya sea redacción, estructura, etc.);
• — , , , .

Hace solo 3 años solo teníamos 8 escritores técnicos. Cuando llegó alguien nuevo, estudió las guías existentes y comenzó a escribir aproximadamente en la misma línea. Fue un momento maravilloso cuando todos tuvimos la misma sensación de belleza, y sin esfuerzo pudimos llegar a un entendimiento común sobre cómo escribir documentación para nuestros productos.

Pasó el tiempo, la empresa creció, había más productos y era necesario aumentar el personal de los escritores técnicos. Hoy ya somos 18 personas y no planeamos parar allí. Todo estaría bien, pero de repente resultó que con tanta gente estar de acuerdo en lo bello se vuelve difícil. Se necesita tiempo, tiempo y nuevamente tiempo.

Con el fin de reducir los costos de energía para transferir el conocimiento a los recién llegados, así como para arreglar de una vez por todas lo que es "hermoso" en la documentación técnica de Veeam, se decidió crear nuestra propia guía de estilo. Debo decir que algunos bocetos sobre el tema del estilo ya han existido durante muchos años en forma de artículos sobre Confluencia y notas marginales en los cuadernos, pero todo esto fue desordenado, fragmentado y, por supuesto, para hablar sobre cualquier facilidad de uso y relevancia de la información. no tuve que.

Fue:



cuando creamos nuestra guía de estilo, tomamos como base 3 guías grandes, que generalmente se toman como muestra al escribir la documentación: ( Chicago Manual of Style , Microsoft Manual of Style y DITA Best Practices), estudió una serie de guías de estilo de terceros que existen con otras compañías (por ejemplo, IBM Style Guide , Documentation Style Guide for OpenSolaris y otras), realizó un estudio de las últimas tendencias en el campo de la documentación, y combinó todo esto con nuestros propios once años de experiencia en Veeam Software.

Se convirtió en:



Como resultado, la Guía de estilo de escritura técnica de Veeam incluía temas de actualidad como estructurar contenido por tipo de tema, principios en inglés simple, puntuación, artículos, formato, creación de capturas de pantalla y diagramas, creación de enlaces a su propia documentación y la de terceros, así como recordatorios útiles para todos los días.

Con el advenimiento de la guía de estilo, no solo facilitamos el proceso de transferencia de conocimiento a los nuevos empleados, sino que también recibimos las siguientes ventajas:

• evitando la necesidad de buscar en reptiles de terceros y en Internet las respuestas a las preguntas que surgen de manera regular;
• resolución instantánea de cuestiones controvertidas con respecto al lenguaje, diseño y estructura de documentos;
• navegación conveniente a través de su propia base de conocimiento;
• la capacidad de proporcionar enlaces a secciones específicas a colegas de otros departamentos que trabajan directa o indirectamente con la redacción de textos (ya sea Soporte o Control de calidad).

Un famoso meme sobre cómo cambia drásticamente el estilo de escritura después de trabajar como escritor técnico.

Nuestra guía de estilo fue creada por hablantes no nativos (hablantes no nativos) y estaba destinada a hablantes no nativos. Sin embargo, fue leído y verificado por nuestros hablantes nativos, lingüistas de marketing que tienen la educación adecuada, han escrito textos largos para el sitio web de la compañía y han desarrollado su propia guía de estilo, también basada en los principios de los gigantes mencionados. industria.

Actualmente estamos trabajando para ampliar nuestra base de conocimiento. Queremos crear guías de estilo separadas para documentos de referencia, como la referencia de API REST y la referencia de PowerShell. Para dichos documentos, el contenido debe estructurarse de una manera especial, y esto debe arreglarse para mantener la uniformidad entre los productos.

Estaremos encantados de que nuestra guía de estilo sea ​​útil para otras compañías que todavía están buscando su propio estilo. Le aconsejo que consulte la sección con información básica , que, según nuestra experiencia, a menudo se necesita en el trabajo: hay muchas cosas interesantes. :)

Guía de estilo de escritura técnica de Veeam (inglés)