Por que você precisa de um Arquiteto de Conteúdo para escalar a documentação da sua empresa

Olá, Habr!

Meu nome é Alisa Komissarova, e sou chefe do departamento de automação e suporte de documentação da Positive Technologies.

Se você trabalha como escritor técnico, é provável que suas tarefas se limitem ao desenvolvimento de documentação do usuário para um produto ou direção. Você está acostumado a usar ferramentas de documentação populares, conhece suas funções básicas e sabe escrever e publicar manuais. Mas o que mudará se você tiver a tarefa de manter a documentação de todos os produtos da empresa, cobrindo muitos subsistemas, versões, plataformas, públicos e todas as etapas do ciclo de vida do produto? O conhecimento do guia de estilo e dos princípios gerais de redação de textos será suficiente?

Há dez anos, a equipe de escritores técnicos da Positive Technologies recebeu exatamente esse desafio - a empresa estava crescendo ativamente e era necessário construir um sistema unificado de documentação. Neste artigo, reuni recomendações práticas que o ajudarão a passar de uma abordagem local para uma abordagem corporativa, bem como a entender por que a função de um arquiteto de conteúdo é necessária.

Escolhendo a ferramenta

Para construir um sistema de documentação corporativa, você primeiro precisa escolher uma ferramenta comum para todos os autores. Ele permitirá criar, editar, salvar e publicar vários conteúdos de produtos, tanto na forma de documentos eletrônicos quanto na forma de ajuda online. Ao escolher a ferramenta certa, você criará uma base confiável para uma documentação uniforme e gerenciada.

Ao escolher uma ferramenta para documentação de produtos, preste atenção aos seguintes recursos:

• Ferramentas para formatação de texto.
• Uma ampla seleção de estilos de parágrafos e caracteres, bem como a capacidade de criar seus próprios (para texto, imagens, listas de verificação, tabelas de preços, formulários, etc.).
• Escalabilidade com o aumento da carga.
• Suporte para o trabalho simultâneo de um grande número de autores e gerenciamento eficaz do crescente volume de conteúdo.
• Localização conveniente.
• Visualização do histórico e status da tradução, upload automático de conteúdo para tradução ao alterar os materiais originais, suporte para tradução do glossário.
• Acordo e revisão.
• Armazenamento de comentários, manutenção de um diário de alterações, geração de relatórios de revisão, criação de uma interface clara para editores e revisores.
• Personalização.
• A capacidade de estender as propriedades dos objetos (por exemplo, atribuir uma versão de orientação de livro ou álbum às tabelas ou selecionar uma linguagem de programação para o bloco de código para determinar o método de destaque de sintaxe), adicionar metadados e integrar a ferramenta aos processos de negócios existentes (por exemplo, via API, plugins ou scripts).

Um arquiteto de conteúdo o ajudará a avaliar a conformidade da ferramenta com suas reais necessidades de informação, a escalabilidade da estrutura de dados e os futuros custos de suporte ao conteúdo. Você pode ler sobre como escolhemos uma ferramenta para gerenciamento de conteúdo corporativo aqui.

De acordo com nossa experiência e a experiência de colegas do setor, essa etapa de transição para um sistema corporativo de gerenciamento de conteúdo pode levar de dois meses a vários anos.

Estruturando o conteúdo na base

Quando a ferramenta é selecionada, você pode começar a migrar seu conteúdo ou criá-lo do zero. Para iniciar o trabalho, é necessário concordar com as regras. Sem uma estrutura clara, as informações se transformam em uma massa caótica que não pode ser usada de forma eficaz em sites ou portais corporativos. Uma arquitetura de dados bem pensada na base e no repositório lhe dará uma série de vantagens:

• Reutilização - projete o conteúdo como um conjunto de blocos independentes e reutilizáveis, e não como seções de documentos. Cada fragmento deve resolver uma tarefa e, em seguida, pode viver em contextos diferentes.
• Automação de processamento - com a organização correta, você pode aplicar as mesmas regras a grupos inteiros de objetos do mesmo tipo (atualização em massa, renomeação, migração, etc.).
• Pesquisa acelerada - uma hierarquia clara de tópicos, tipos e tags permite que os autores encontrem rapidamente o material certo, sigam um formato unificado e excluam a duplicação de conteúdo.
• Controle de acesso - o conteúdo estruturado simplifica a configuração de direitos: você pode restringir a visualização de seções confidenciais e fornecer direitos para editar categorias individuais de conteúdo apenas para especialistas líderes.

Um arquiteto de conteúdo define a organização lógica das informações, suas inter-relações, regras de armazenamento e disponibilidade para o usuário. Ele desenvolve acordos unificados para todos os autores da empresa e monitora sua conformidade.

Uma abordagem consistente e clara para o armazenamento de conteúdo nos permite manter simultaneamente materiais de marketing, documentação técnica e de projeto, bem como recursos para vendas, pilotagem e outros tipos de materiais. Por exemplo, em um dia útil, podemos lançar uma atualização do EULA para 26 produtos da empresa em vários idiomas de localização. O EULA pronto é sincronamente colocado no portal de referência (consulte a seção “Acordo de licença”) e incluído nas distribuições de produtos. Atingimos esse ritmo devido à reutilização de 95% do texto entre diferentes acordos de licença com usuários finais, bem como processos estabelecidos de preparação, revisão e publicação de conteúdo - mais sobre isso nos pontos subsequentes do artigo.

Verificações regulares de conteúdo

Qualquer conteúdo, independentemente de quem o criou, precisa ser verificado. Verificações regulares são um elemento-chave de qualquer sistema de gerenciamento de conteúdo maduro. Eles são necessários não “por hábito”, mas para que a base de documentação permaneça precisa e atualizada.

A edição final do texto não é apenas vírgulas corrigidas, mas um material pronto para publicação que é escrito corretamente, fácil de ler e benéfico para o público. Para garantir a qualidade consistente do conteúdo, recomendamos construir o seguinte processo:

• Desenvolva um estilo de documentação e siga-o no futuro, crie uma base de conhecimento centralizada da equipe.
• Configure verificações automáticas (verificação de estrutura, terminologia, conformidade com modelos, etc.). Eles ajudam a detectar erros simples, reduzir a carga no editor e protegê-lo.
• Organize fluxos de trabalho automáticos para revisão: o autor transfere o material para edição com um clique, e o sistema registra o status (em revisão, requer revisão, aprovado).
• Colete e analise métricas de revisão - a porcentagem de conteúdo revisado, o tempo médio de passagem do fluxo de trabalho, o número de edições por tipo. Esses dados permitem que você veja os “gargalos”. Por exemplo, se um escritor técnico frequentemente comete erros estilísticos - ele precisa estudar novamente o guia de estilo corporativo. Se os textos de um autor exigirem mais de 3 revisões - ele precisa usar verificações automáticas com mais frequência e envolver IA na revisão antes de enviar para revisão.

Essas tarefas de arquitetura da informação vão além das responsabilidades habituais dos principais escritores técnicos.

É a função do arquiteto de conteúdo que combina pensamento editorial, design de cenários de usuário, trabalho com dados e design de sistema.

Em nosso caso, conteúdo de alta qualidade e reutilização nos permitem reduzir o tempo de localização em 35-50% e lançar produtos em lançamento imediatamente com um pacote de documentos em vários idiomas.

Configurando a publicação

Conteúdo não é apenas texto escrito, mas também a forma como ele é entregue ao usuário. Os layouts de materiais de marketing e técnicos devem ser diferentes: eles têm metas, público e requisitos de estrutura diferentes, portanto, cada tipo de conteúdo precisa de sua própria abordagem para publicação. Não crie conteúdo “do zero” para cada canal. Depois de escrever a versão principal do material, “reveste-o” no formato certo de acordo com o layout selecionado e as regras de entrega. Isso permitirá que você lance rapidamente o mesmo texto sem esforço repetido.

O que precisa ser feito:

• Para cada tipo de material, prepare os layouts apropriados (por exemplo, para publicação nos formatos PDF, HTML, DOCX, MD, JSON, PPTX, TXT, etc.).
• Preveja a possibilidade de atualizar a identidade corporativa - alterações nas cores corporativas, fontes e outros elementos visuais - por exemplo, como parte de rebrandings planejados, que temos a cada 3-4 anos.
• Se necessário, defina uma programação de publicações automáticas (diariamente, semanalmente, por evento) e defina as regras de gatilho que iniciarão o processo de publicação.

Essas tarefas são geralmente atribuídas ao arquiteto de conteúdo, que acompanha todos os projetos e leva em consideração as nuances ao formular requisitos para futuras alterações nos modelos e layouts de publicação.

A capacidade de publicar o mesmo conteúdo no portal de referência, na forma de ajuda integrada ao produto, bem como no formato DOCX para transferência para certificação e em PDF para transferência para parceiros, nos permite reduzir o tempo de preparação do lançamento em 20-30%, por exemplo, nos produtos MaxPatrol SIEM, MaxPatrol EDR, PT Sandbox, PT NAD e PT AF PRO.

Gerenciamento do ciclo de vida do conteúdo

Depois que o conteúdo é publicado, o trabalho nele não para. Ele começa a atender usuários reais, e a equipe - monitorar sua viabilidade.

O ciclo de vida do conteúdo é um processo sistemático de gerenciamento de conteúdo, cobrindo todos os estágios (planejamento, criação, controle, publicação, promoção, análise de eficácia e atualização, até o arquivamento ou exclusão final). Para gerenciar totalmente o conteúdo, implemente as práticas listadas abaixo:

• Pense na taxonomia e nos modelos de classificação, independentemente do sistema de documentação específico. A arquitetura de conteúdo deve ser tal que você possa alterar a ferramenta a qualquer momento.
• Defina atributos de ciclo de vida nos metadados: data de criação, data da última verificação e responsável pelo conteúdo e publicação. Isso simplifica o rastreamento de status e o planejamento de atualizações.
• Se seu conteúdo estiver hospedado em portais, colete dados sobre o comparecimento de páginas e analise o comportamento do usuário. Essas métricas permitirão que você planeje futuras reestruturações.
• Verifique periodicamente a base em busca de links quebrados, fragmentos desatualizados e duplicatas. Limpar o excesso melhora a qualidade da pesquisa e reduz a carga no sistema.
• Configure notificações automáticas que notificarão sobre a quebra de conexões entre fragmentos, sobre obsolescência ou a necessidade de arquivamento. Isso ajuda a responder às mudanças em tempo hábil sem controle manual.

A abordagem sistemática garante a relevância, disponibilidade e integridade da documentação corporativa ao longo de sua vida.

Lançamos pelo menos 5 processos automáticos de verificação da base a cada mês e, a cada trimestre, conduzimos uma auditoria da qualidade e do nível de reutilização do conteúdo. Essa automação é impossível sem um arquiteto de conteúdo, profundamente imerso nos processos e participando ativamente do desenvolvimento e implementação de tecnologias e sistemas de documentação.

Conclusões

Para implementar todas as recomendações listadas para construir um sistema de documentação corporativa, você precisa de um arquiteto de conteúdo na equipe. As habilidades de um escritor técnico não são mais suficientes. A principal diferença entre eles é a escala do trabalho e a responsabilidade: o arquiteto de conteúdo projeta a estrutura, o sistema e o ciclo de vida da documentação, enquanto o escritor técnico se concentra na criação do próprio conteúdo. Quando essas pessoas trabalham de forma suave e eficaz, os usuários da documentação se beneficiam - o conteúdo aparece no momento certo, parece uniforme e, portanto, se torna previsível e compreensível.

Tags:

• Gerenciamento de produtos
• Documentação técnica
• CMS
• Doc-as-a-code
• Estratégia de conteúdo