4 níveis de maturidade de documentação DevOps
A documentação do DevOps requer uma jornada semelhante à que você percorreu para atingir a maturidade do DevOps ou DevSecOps.
DevOps e DevSecOps exigem práticas ágeis de documentação para entregar documentação de qualidade no prazo com um ciclo iterativo de entrega de software. É uma jornada semelhante ao DevOps, com uma mudança para a automação e uma abordagem mais ágil ao conteúdo. Se a documentação só agora está entrando nas discussões sobre DevOps da sua organização, é hora de atualizar suas práticas de documentação até o DevOps.
Aqui estão os quatro níveis de maturidade da documentação DevOps:
Nível 1: Ad hoc e isolado
No primeiro nível de maturidade da documentação do DevOps (mais imaturo), os esforços de documentação não se alinham com os esforços do DevOps. O desenvolvimento do DevOps segue seu caminho enquanto a equipe de documentação segue um caminho separado, o que muitas vezes faz com que a documentação fique por trás do desenvolvimento. Atrasar o lançamento de um produto por causa da documentação não é uma opção no mundo hipercompetitivo da nuvem.
Pessoal
A equipe de documentação neste nível não se desviou da antiga maneira de fazer as coisas. Os redatores técnicos ainda trabalham em uma equipe centralizada separada das equipes de desenvolvimento. Um abismo entre o grupo de redação técnica e as equipes de desenvolvimento ocorre por vários motivos, incluindo:
- Políticas corporativas que criam divisões e silos de equipe
- A equipe vê a documentação técnica como uma marca de verificação, não como um ativo que cria o sucesso do projeto
- A contratação de redatores técnicos em uma reflexão tardia
- Desalinhamento das prioridades dos redatores técnicos com as realidades da equipe de desenvolvimento
Outro sinal dos desafios de pessoal nesta fase é a “definição do que está pronto”. É aqui que os escritores técnicos novos na experiência ágil podem achar um desafio trabalhar com aplicativos desenvolvidos por meio da iteração de cadeias de ferramentas e processos de integração contínua/desenvolvimento contínuo (CI/CD).
Ferramentas e processos de documentação
Os redatores técnicos nesta fase usam ferramentas com as quais estão acostumados no trabalho de escritório tradicional, como suítes de escritório e programas de layout. As ferramentas não são ágeis e exigem controle de versão, e os requisitos de gerenciamento de conteúdo não se integram de forma eficiente às cadeias de ferramentas DevOps nem suportam a velocidade de desenvolvimento. Os redatores técnicos ainda seguem modelos e processos legados neste nível.
Resultados
Os resultados da documentação neste nível podem não estar atualizados ou até mesmo carecer de precisão técnica. Quando uma equipe de desenvolvimento avança na velocidade do DevOps e seu suporte técnico ao redator segue um processo legado não ágil (usando ferramentas proprietárias e formatos de entrega), é difícil iterar a documentação e acompanhar as mudanças no aplicativo.
Nível 2: Experimentação e piloto
O segundo nível de maturidade da documentação do DevOps (fase de experimentação) é onde os líderes e redatores técnicos do DevOps dão os primeiros passos para implementar práticas e ferramentas de documentação mais ágeis.
Idealmente, a experimentação faz parte de um projeto piloto com o apoio das partes interessadas que têm mais a ganhar com a melhoria da entrega de documentação e a sua integração com práticas de DevOps.
Pessoal
A contratação de pessoal na fase experimental pode assumir uma de três formas:
- Um redator técnico com visão de futuro que experimenta ferramentas mais ágeis em seu próprio tempo, traz suas descobertas para o trabalho porque deseja uma maneira melhor de fazer seu trabalho. O redator apresenta à sua liderança a ideia de um processo de documentação mais ágil.
- O líder ou engenheiro de DevOps está experimentando ferramentas como Hugo e Jekyll e integrando a ferramenta ao pipeline de CI/CD. A equipe DevOps ensina as ferramentas ao redator técnico.
- A equipe contrata prestadores de serviços ou consultores terceirizados com experiência em ferramentas de documentação de DevOps e conhecimento de onde as ferramentas de documentação se encaixam na cadeia de ferramentas de CI/CD e no ciclo de vida de DevOps.
Ferramentas e práticas de documentação
Hugo e Jekyll estão entre as ferramentas que aparecem nessa fase. Esta fase também vê novas abordagens para estratégia de conteúdo e redação técnica.
Resultados
O resultado de uma fase de experimentação bem-sucedida deve ser “aterrissar e expandir” e estabelecer práticas de documentação de DevOps que outras equipes de projeto possam colocar em prática.
A experimentação nesta fase também inclui mudanças fundamentais na estratégia de conteúdo e nos processos de publicação, que os redatores técnicos fora do projeto piloto podem aprender e adotar.
Uma mudança nas práticas de contratação de redatores técnicos é outro resultado potencial desta fase com base no sucesso do piloto. É essencial trazer seus redatores internos, oferecendo-lhes treinamento sobre DevOps e suas ferramentas de documentação recém-implementadas.
Novas ferramentas e processos de documentação são os resultados críticos desta fase. Você também precisará vender esse resultado para sua liderança, partes interessadas e outras equipes por meio de apresentações, relatórios de status e estudos de caso internos.
Nível 3: Automação e expansão parcial
O terceiro nível de maturidade da documentação DevOps (automação e expansão parciais) é o próximo passo no resultado de “aterrar e expandir”. Nesta fase, outras equipes de DevOps adotam as ferramentas, práticas e lições de documentação de DevOps aprendidas no projeto piloto.
Pessoal
Os redatores técnicos e as equipes de DevOps iniciam uma colaboração muito mais estreita nesse nível. A contratação de novos redatores técnicos neste nível concentra-se em redatores com experiência em ambientes DevOps.
Ferramentas e práticas de documentação
Os redatores técnicos começam a migrar de suas ferramentas e processos legados e a adotar ferramentas de documentação mais ágeis durante esta fase, como:
- docToolchain
- Documento
- Hugo
- Jekyll
Os redatores técnicos também trabalham para ajustar suas práticas legadas nesse nível.
Resultados
As ferramentas e práticas de documentação do DevOps vão além do(s) projeto(s) piloto para se tornarem práticas padrão. O aprendizado contínuo é essencial neste nível, à medida que novas equipes entram em operação com novas ferramentas e processos de documentação.
Nível 4: Adoção total
O nível mais alto de maturidade da documentação DevOps (adoção total e automação) é onde as ferramentas, práticas e processos estão implementados para dar suporte à documentação como uma prioridade de projeto de nível superior. Alcançar esse nível de maturidade requer experimentação, iteração e colaboração.
Pessoal
A automação total reúne a colaboração mais próxima entre a equipe DevOps e os redatores técnicos. Uma marca dessa fase é que seus redatores técnicos ficam firmemente integrados ao fluxo de trabalho da equipe do projeto. Grandes empresas com engenheiros designados para manter cadeias de ferramentas DevOps assumem tarefas de manutenção nas ferramentas de documentação.
Ferramentas e práticas de documentação
Os redatores técnicos neste nível de maturidade são padronizados em linguagem de remarcação e ferramentas automatizadas.
Resultados
Os resultados desta fase são um conjunto completo de ferramentas e práticas que apoiam a automação da publicação de documentação online. Os redatores técnicos podem publicar e republicar a documentação conforme necessário para apoiar um processo de desenvolvimento iterativo.
A aprendizagem contínua é outro resultado desta fase. Os redatores técnicos e os mantenedores do conjunto de ferramentas buscam maneiras de melhorar a automação e os processos que auxiliam nas práticas de documentação.
Pensamentos finais
A documentação do DevOps requer uma jornada semelhante à que você percorreu para atingir a maturidade do DevOps ou DevSecOps. Espero chegar a um ponto em todos os setores onde a mudança para práticas e ferramentas de documentação mais ágeis se torne parte da jornada geral de DevOps de uma organização. Ainda há trabalho a ser feito. O avanço da maturidade da documentação do DevOps deve fazer parte da maturidade geral do DevOps ou mesmo da transformação do DevOps para DevSecOps.