Analytics
8
min de leitura
25 de junho de 2020

Tratando Documentação como Código: como documentar de forma ágil

Fernanda Goulart
Escritor Técnico
PhD em política científica e tecnológica, trabalho na revisão da documentação global para desenvolvedores da Sensedia.
Mais sobre o autor

A proliferação de metodologias ágeis transformou muitas coisas no mundo de desenvolvimento de software, incluindo a documentação. O Manifesto Ágil cita a questão logo de cara, e não de forma muito simpática, declarando a valorização de “software em funcionamento mais que documentação abrangente”. Esse trecho do Manifesto tem sido um pretexto para deixar a documentação de lado, já que ela se configuraria mais como um desperdício de recursos do que como um ativo que agrega valor ao produto.

Entretanto, essa visão é falha, e é inclusive desautorizada pelo próprio Manifesto, que afirma que “mesmo havendo valor nos itens à direita, valorizamos mais os itens à esquerda.” Ou seja, a documentação tem valor — mesmo quando falamos de metodologia ágil — ainda que seja importante não colocar a documentação em um patamar superior ao produto em funcionamento.

Sim, documentação gasta recursos, como qualquer atividade corporativa. Por isso, documentar demais é sim um gasto desnecessário, tanto em termos de tempo e esforço pessoal quanto de espaço para manutenção dos arquivos. Mas documentar de menos, ou documentar mal, também é um desperdício de recursos. E isso pode se refletir, por exemplo, em chamados de suporte desnecessários pela falta de material de apoio aos clientes e em mais tempo e esforço no treinamento de novos colaboradores nos times de desenvolvimento.

É por isso que a decisão de o quê, quanto e como documentar deve sempre levar em consideração os riscos e custos de documentar mais ou menos que o suficiente. A questão principal, então, não é se devemos ou não documentar (devemos!), mas sim como podemos encontrar a medida certa de uma documentação que seja, como o processo de desenvolvimento de produtos, ágil.

Documentação de código

Eu sustento que a primeira coisa fundamental para encontrar essa medida é não fazer uma clivagem grande demais entre a documentação e o código do produto. Mesmo quando nos referimos a documentos técnicos para o usuário final, como manuais e tutoriais, que são o foco principal do que chamo de “documentação técnica” neste texto. De fato, há um conceito cada vez mais difundido a respeito disso, o “doc as code”, que prega exatamente que a documentação seja vista e produzida como código (ou, como chamo neste texto, que tenhamos uma “documentação-código”).

A ideia fundamental por trás desse conceito é que tratar textos de produto como código — inclusive usando as mesmas ferramentas aplicadas ao desenvolvimento de softwares —  permite incluir a documentação dentro do planejamento de entrega dos produtos. Isso reduz inconsistências entre documentação e produto, facilita a manutenção de uma documentação atualizada e evita retrabalho desnecessário.

E essa alteração na forma de ver documentação pode ter um impacto positivo bastante significativo na qualidade do processo de escrita e publicação de textos. Isso porque as ferramentas de codificação, revisão e versionamento — e também as metodologias de gerenciamento de projetos —  que são de amplo uso no desenvolvimento de softwares tornam o processo de desenvolvimento de documentação mais rápido, colaborativo e organizado.

Para especificar mais o funcionamento e vantagens de uma documentação-código, vamos pensar em duas dimensões do desenvolvimento de documentação: a escrita dos textos e o processo mais amplo de acompanhamento do ciclo de vida de cada documento, que inclui a sua escrita, mas também o seu design, revisões, testes, publicação, melhoria contínua e análise de métricas. Podemos chamar este processo mais geral de fluxo de trabalho, ou workflow, termo generalizado nas empresas de tecnologia.

Processo de escrita

Quando você precisa escrever um texto que não terá que ser atualizado frequentemente e só precisará convertê-lo para PDF uma vez, o Word é realmente uma ótima opção. Mas um documento técnico é, cada vez mais, um organismo vivo. Ele sempre precisa ser revisto e melhorado, usualmente de forma colaborativa, conforme ocorrem mudanças nos produtos, e a maior parte das vezes é publicado em sites, não (exclusivamente) compartilhado como PDF. Arquivos binários, como os .doc, que são pesados, ocupam bastante espaço em disco, e necessitam de processadores de texto para serem escritos e visualizados, simplesmente não são a escolha adequada para a imensa maioria de documentos técnicos.

Tratar documentação como código significa, em primeiro lugar, que ela deve existir no mesmo ambiente que o código. Isso, seguindo as práticas mais comuns, quer dizer que ela será mantida em repositórios de código com suporte a versionamento (ou, mais especificamente, a controle de versão distribuído), como o Github e o Bitbucket. E o formato do arquivo deve ser aceito pelo serviço de repositórios, o que nos leva aos formatos de texto puro, que são leves e podem ser visualizados em qualquer editor de texto.

Mas isso não quer dizer que vamos escrever documentação de produto em TXT e usando o bloco de notas. Quanto ao formato, há muitas linguagens de texto puro com sintaxe para elementos de formatação e layout. É o que chamamos de linguagens markup. Pessoalmente, eu sou discípula do AsciiDoc, mas você pode preferir Markdown ou RestructuredText. Quanto aos editores de texto, há uma miríade de ótimas opções. Eu, por exemplo, utilizo o Atom, onde consigo instalar pacotes para facilitar o meu processo de escrita. Além de realce de sintaxe AsciiDoc, uso uma ferramenta para checar erros de ortografia e tiro vantagem da funcionalidade de busca e substituição de termos, muito superior à que eu teria em um processador de texto. Por meio de expressões regulares, encontro e substituo palavras ou frases rapidamente em um arquivo ou em um projeto inteiro. A própria organização de textos em projetos já é um benefício enorme. É mais fácil achar o texto que você precisa, pois você enxerga as pastas de um projeto dentro do seu editor. E como cada arquivo é muito leve, é fácil também abrir e trabalhar com vários arquivos ao mesmo tempo, inclusive dividindo uma mesma tela.

Não há nada de novo aqui para os desenvolvedores que escrevem documentação técnica, pois eles já estão acostumados com os editores de texto para codar, mesmo que por ventura escrevam documentação em processadores de texto. Por sua vez, os technical writers que não são desenvolvedores podem sofrer um pouco ao abandonar os processadores WYSIWYG (“o que você vê é o que você obtém”). Mas é fácil se acostumar com coisa boa, e as vantagens da documentação-código superam, e muito!, as desvantagens.

Workflow

Para além das alterações no processo de escrita do texto em si, o aspecto que julgo ser o principal ponto forte da documentação-código é a facilidade de integração da documentação no workflow seguido para o desenvolvimento de produtos.

Manter o texto em repositórios de código significa usufruir das ferramentas não só de versionamento mas também de acompanhamento do ciclo de vida de um texto ao longo das suas diferentes etapas de desenvolvimento, devidamente refletidas em branches distintas dentro de um mesmo repositório. Com isso, é possível inserir o texto no planejamento do produto como um todo, incluindo-o no âmbito do gerenciamento do projeto e seguindo as mesmas boas práticas de revisões e testes antes de entrar em produção.

Como para os softwares, é possível resolver problemas na documentação por meio de hotfixes ou bugfixes, cada qual com sua respectiva branch, e provisionar versões de lançamento de documentação junto com as versões dos produtos. Mais do que isso, o texto se torna de fato uma entidade viva — constantemente atualizada — e é mais fácil compartilhar o trabalho entre um time, seja quando há mais de um autor por texto, seja quando há um autor só mas o processo de revisão é descentralizado entre os vários desenvolvedores da equipe.

Com o texto integrado ao produto, é mais fácil também coordenar os diferentes papéis. Os technical writers ficam menos deslocados e passam a fazer parte do time de desenvolvimento. Essa integração se torna uma via de mão-dupla para a colaboração. Por um lado, os technical writers se sentem mais à vontade para pedir o input dos desenvolvedores para a produção do texto; por outro, eles podem ocasionalmente também contribuir para o próprio produto. Isso porque eles têm que aprender sobre cada detalhe dos produtos e testá-los com o cliente final em mente. Isso pode gerar insights e contribuir para a detecção de bugs. É claro que esse não é o objetivo do trabalho de um technical writer, mas não deixa de ser uma externalidade bem-vinda.

Para concluir: o planejamento é o objetivo

Este texto buscou mostrar algumas das grandes vantagens de tratar documentação como código. Só é preciso ressaltar que essas vantagens não implicam que todos os textos técnicos têm que ser escritos dessa forma.

Lembre-se que “ágil” não é uma metodologia, um processo específico e bem definido, mas antes um conjunto de valores, um modo de pensar e organizar a arquitetura e o desenvolvimento de softwares. Ser ágil é, antes de tudo, avaliar e implementar a forma mais adequada de chegar a um determinado fim gastando o mínimo de recursos possível.

Aplicando essa lógica à documentação, nem sempre o workflow que eu citei aqui será a melhor alternativa. A depender da audiência dos seus textos, da cultura de desenvolvimento da sua equipe de produto, das necessidades específicas de publicação que você tem, você pode chegar a conclusões diferentes das minhas.

De qualquer forma, se o foco é escrever de forma ágil, vale repensar as práticas de documentação. Estou documentando demais? Estou documentando bem menos do que deveria? Qual o ciclo de vida dos textos que produzo? Quais os tipos de texto que precisamos gerar e qual o método ideal de publicação para cada tipo? Responder a essas perguntas é o primeiro passo para escrever documentação ágil. E, depois de respondê-las, o que vale é planejar o fluxo da sua documentação.

Obrigado pela leitura!