Um guia DevOps para documentação

Traga a redação da sua documentação para o ciclo de vida do DevOps.

O DevOps está desafiando as normas de documentação técnica como nunca antes na história da TI. Da automação ao aumento da velocidade de entrega e ao desmantelamento do modelo de ciclo de vida de desenvolvimento de software em cascata, tudo isso significa a necessidade de fazer mudanças drásticas nos negócios e na filosofia da documentação técnica.

Aqui estão algumas maneiras pelas quais o DevOps está influenciando a documentação técnica.

A mudança do papel do redator técnico

A função do redator técnico deve se adaptar ao DevOps. A boa notícia é que muitos redatores técnicos já estão integrados em equipes de desenvolvimento e podem ter uma vantagem por já terem relacionamentos colaborativos e conhecimento crescente do produto.

Mas você terá que fazer algumas mudanças se seus redatores técnicos estiverem acostumados a trabalhar em silos e a confiar em rascunhos escritos por especialistas no assunto como base para a documentação.

Faça investimentos para garantir que sua documentação e outros esforços de desenvolvimento de conteúdo relacionados ao projeto obtenham as ferramentas, a estrutura e o suporte necessários. Comece mudando suas práticas de contratação de redatores técnicos. A documentação na velocidade do DevOps exige repensar sua estratégia de conteúdo e quebrar silos de longa data entre sua equipe de DevOps e o redator técnico designado para dar suporte ao projeto.

O DevOps também faz com que as equipes de desenvolvimento se afastem dos rigores das práticas tradicionais de documentação. Acima de tudo, a definição de concluído da documentação deve mudar. Algumas culturas corporativas tornam o redator técnico um participante passivo no desenvolvimento de software. O DevOps faz novas demandas – à medida que avança a transformação cultural do DevOps, o mesmo acontece com o papel do redator técnico. Os escritores precisarão (e deverão se ajustar) à transparência que o DevOps oferece. Eles devem se integrar às equipes DevOps. Dependendo de como a organização define a função, trazer o redator técnico para a equipe pode apresentar desafios de conjunto de habilidades.

Padrões, metodologias e especificações de documentação

Embora o DevOps ainda não tenha influenciado a documentação técnica em si, a comunidade de código aberto se intensificou para ajudar com a documentação da interface de programação de aplicativos (API) que está sendo usada entre equipes de DevOps em empresas de todos os tamanhos.

Especificações e ferramentas de código aberto para documentar APIs são uma área interessante de se observar. Eu gostaria de pensar que isso se deve à influência do Google Season of Docs, que dá aos projetos de software de código aberto acesso a talentos profissionais de redação técnica para lidar com seus projetos de documentação mais críticos.

APIs de código aberto estão disponíveis e precisam fazer parte da discussão da documentação do DevOps. A importância dos requisitos de integração de aplicativos nativos da nuvem está aumentando. A especificação OpenAPI — um padrão aberto para definir e documentar uma API — é um bom recurso para documentação de API em ambientes DevOps. No entanto, uma crítica significativa é que a especificação pode tornar a documentação demorada para ser criada e mantida atualizada.

Houve breves tentativas de criar uma metodologia de Documentação Contínua. Houve também um movimento para criar um DocOps Framework que saiu da CA (agora Broadcom). Apesar da sua promessa inicial, o DocOps nunca se tornou um movimento da indústria.

O estado atual dos padrões de documentação DevOps significa que suas equipes de DevOps (incluindo seu redator técnico) precisam começar a criar documentação nos estágios iniciais de um projeto. Você faz isso adicionando documentação tanto como uma história ágil quanto (tão importante) como uma expectativa de gerenciamento; você o aplica vinculando-o a avaliações anuais de desempenho.

Ferramentas de documentação

A criação da documentação DevOps deve ocorrer online em um formato ou plataforma acessível a todos os membros da equipe. MediaWiki, DokuWiki, TikiWiki e outros wikis de código aberto oferecem às equipes de DevOps um repositório central para criação e manutenção de documentação.

Deixe as equipes escolherem seu wiki da mesma forma que você permite que escolham outras cadeias de ferramentas de integração contínua/desenvolvimento contínuo (CI/CD). Parte do poder dos wikis de código aberto é a sua extensibilidade. Por exemplo, o DokuWiki inclui uma variedade de extensões que você pode instalar para criar uma plataforma de autoria que atenda aos requisitos de autoria da sua equipe DevOps.

Se você for ambicioso o suficiente para reforçar os recursos de autoria e colaboração de sua equipe, Nextcloud (um pacote de colaboração em nuvem de código aberto) é uma opção para colocar suas equipes de DevOps online e fornecer-lhes as ferramentas necessárias para criar documentação.

Melhores práticas de DevOps

A documentação também desempenha um papel na transformação do DevOps. Você vai querer documentar as práticas recomendadas que ajudam sua organização a obter eficiência e ganhos de processo com o DevOps. Essas informações são importantes demais para serem comunicadas apenas de boca em boca entre suas equipes de DevOps. A documentação é uma força unificadora se sua organização tiver várias equipes de DevOps; ele promove a padronização das melhores práticas e prepara você para capturar e avaliar métricas de qualidade do código.

Muitas vezes são os desenvolvedores que assumem o trabalho de documentar as práticas de DevOps. Mesmo que suas organizações tenham redatores técnicos, eles podem trabalhar entre equipes de desenvolvimento. Portanto, é importante que os desenvolvedores e administradores de sistemas possam capturar, documentar e comunicar suas melhores práticas. Aqui estão algumas dicas para levar esse esforço na direção certa:

• Invista tempo antecipadamente para criar um modelo padrão para suas práticas recomendadas de DevOps. Não caia na armadilha de copiar um modelo encontrado online. Entreviste suas partes interessadas e equipes para criar um modelo que atenda às necessidades de sua equipe.
• Procure maneiras de ser criativo na coleta de informações, como gravar as reuniões de sua equipe e usar os registros do sistema de bate-papo para servir de base para sua documentação.
• Estabeleça um wiki para publicar suas melhores práticas. Use um wiki que permita manter uma trilha de auditoria de edições e atualizações. Essa plataforma prepara suas equipes para atualizar e manter as melhores práticas à medida que elas mudam.

É inteligente documentar dependências à medida que você cria seus conjuntos de ferramentas de CI/CD. Esse esforço compensa quando você integra novos membros da equipe. Também é uma pequena garantia quando um membro da equipe se esquece de alguma coisa.

Por fim, a automação é atraente tanto para as partes interessadas quanto para os profissionais de DevOps. É tudo diversão e jogos até a automação quebrar. Ter documentação para run books de automação, guias de administração e outras coisas em vigor (e atualizadas) significa que sua equipe pode fazer com que a automação funcione novamente, independentemente de quando ela falhar.

Pensamentos finais

DevOps é um resultado positivo para documentação técnica. Ele puxa o desenvolvimento de conteúdo para o ciclo de vida do DevOps e quebra os silos entre desenvolvedores e redatores técnicos dentro da cultura organizacional. Sem o luxo de um redator técnico, as equipes obtêm as ferramentas para acelerar a velocidade de criação de documentos para corresponder à velocidade do DevOps.

O que sua organização está fazendo para incluir a documentação no ciclo de vida do DevOps? Por favor, compartilhe sua experiência nos comentários.