Agora, um sapateiro com botas, ou Como conseguimos nosso próprio guia de estilo

Suponho que, queridos leitores, em seu trabalho você tenha lidado com documentação técnica e, possivelmente, mesmo com quem a cria - com escritores técnicos. E em nosso blog, você pode conhecer um escritor técnico da equipe Veeam.

Hoje, passamos ao próximo nível de entendimento de como o desenvolvimento da documentação técnica no Veeam Software funciona.

O KDPV está enganando - isso não é um milagre, mas o mesmo trabalho que todos os outros colegas de P&D. No entanto, quem cria guias tem palavras mágicas para criar guias! Aqui está uma recursão.

Leia mais na história da minha colega Daria Shalygin.

Olá, meu nome é Dasha e sou líder de qualidade de conteúdo na Veeam Software. Sou responsável pela qualidade do conteúdo criado pelo departamento de redatores técnicos da nossa empresa. Na prática, sou escritor e editor técnico em uma garrafa. Minhas responsabilidades incluem:

• executando meus próprios projetos - como todos os redatores técnicos, tenho minha área de responsabilidade, ou seja, vários produtos para os quais crio e mantenho a documentação;
• treinamento para funcionários de nível júnior - criei um curso introdutório para "iniciantes", que passo para explicar as regras básicas para escrever documentação;
• assessoria a funcionários de níveis mais altos (experientes e seniores) - tenho sessões diárias agendadas durante as quais qualquer membro de nossa equipe pode me fazer qualquer pergunta sobre a documentação (seja redação, estrutura etc.);
• — , , , .

Apenas 3 anos atrás, tínhamos apenas 8 escritores técnicos. Quando alguém novo chegou, ele estudou os guias existentes e começou a escrever aproximadamente na mesma linha. Foi um momento maravilhoso em que todos tínhamos o mesmo sentimento de beleza e pudemos facilmente chegar a um entendimento comum de como escrever documentação para nossos produtos.

O tempo passou, a empresa cresceu, havia mais produtos e havia uma necessidade de aumentar a equipe de redatores técnicos. Hoje já somos 18 pessoas e não planejamos parar por aí. Tudo ficaria bem, mas de repente aconteceu que com tantas pessoas concordar com o belo se torna difícil. Leva tempo, tempo e novamente tempo.

Para reduzir os custos de energia com a transferência de conhecimento para os recém-chegados, bem como corrigir de uma vez por todas o que é "belo" na documentação técnica da Veeam, foi decidido criar nosso próprio guia de estilo. Devo dizer que alguns esboços sobre o tema do estilo já existem há muitos anos na forma de artigos sobre Confluence e notas marginais em cadernos, mas tudo isso foi desordenado, fragmentado e, é claro, para falar sobre qualquer facilidade de uso e relevância das informações. não precisava.

Era:



Quando criamos nosso guia de estilo, tomamos como base 3 grandes guias, que geralmente são tomadas como amostra ao escrever documentação: ( Chicago Manual de estilo , Microsoft Manual de estilo e DITA Melhores Práticas), estudou vários guias de estilo de terceiros que existem com outras empresas (por exemplo, IBM Style Guide , Documentation Style Guide para OpenSolaris e outros), conduziu um estudo das últimas tendências no campo da documentação - e misturou tudo isso com nossos onze anos de experiência no Veeam Software.

Tornou-se:



Como resultado, o Guia Técnico de Estilo de Redação Veeam incluiu tópicos como estruturação de conteúdo por tipo de tópico, princípios simples de inglês, pontuação, artigos, formatação, capturas de tela e diagramas de desenho, links para a documentação própria e de terceiros, além de lembretes úteis para todo dia.

Com o advento do guia de estilo, não apenas facilitamos a transferência de conhecimento para novos funcionários, mas também recebemos as seguintes vantagens:

• impedindo a necessidade de procurar répteis de terceiros e a Internet por respostas a perguntas que surgem regularmente;
• resolução instantânea de questões polêmicas relacionadas à linguagem, design e estrutura dos documentos;
• navegação conveniente através da sua própria base de conhecimento;
• a capacidade de fornecer links para seções específicas para colegas de outros departamentos que trabalham direta ou indiretamente com a redação de textos (seja Suporte ou QA).

Um meme famoso sobre como o estilo de escrever muda drasticamente depois que você trabalhou como redator técnico.O

nosso guia de estilos foi criado por falantes não nativos (falantes não nativos) e destina-se a falantes não nativos. No entanto, foi lido e verificado por nossos falantes nativos, lingüistas de marketing que possuem a educação adequada, escreveram textos longos para o site da empresa e desenvolveram seu próprio guia de estilo, também com base nos princípios dos gigantes mencionados indústria.

Atualmente, estamos trabalhando para expandir nossa base de conhecimento. Queremos criar guias de estilo separados para documentos de referência, como a Referência da API REST e a Referência do PowerShell. Para esses documentos, o conteúdo precisa ser estruturado de uma maneira especial, e isso precisa ser corrigido para manter a uniformidade entre os produtos.

Teremos o maior prazer em saber se o nosso guia de estilo será útil para outras empresas que ainda buscam seu próprio estilo. Aconselho que você consulte a seção com informações básicas , que, em nossa experiência, são frequentemente necessárias no trabalho - há muitas coisas interessantes. :)

Guia de estilo de redação técnica da Veeam (inglês)