Introdução
Seja muito bem-vindo à nossa documentação. Esta documentação tem como principal objetivo exemplificar como seria uma documentação de um projeto utilizando a ferramenta Docusaurus.
Essa documentação é destinado a armazenar um experimento que estou desenvolvendo para explorar a filosofia da documentação como código (Docs as Code). Essa abordagem propõe que a documentação seja escrita utilizando as mesmas ferramentas empregadas na codificação do projeto.
Em síntese, a documentação como código é uma técnica de desenvolvimento e publicação da documentação de projetos usando as mesmas ferramentas e processos aplicados no desenvolvimento do código. Isso envolve manter os arquivos de documentação junto aos de código em um repositório, facilitando o controle de versões.
Por que Docs-as-code?
Optei por estudar essa filosofia por uma necessidade pessoal sentida ao gerenciar a documentação de meus projetos. Frequentemente, as documentações ficavam dispersas em diferentes plataformas, wikis internas e sistemas de gestão de conteúdo, tornando a publicação de novos documentos um processo trabalhoso.
Nesse cenário, surge um grande caos, pois as documentações estão distribuídas em múltiplas plataformas. A busca por informações específicas consome tempo, e, muitas vezes, a documentação encontrada está desatualizada ou duplicada em diferentes locais, exigindo análise para determinar qual versão é a mais recente.
Por exemplo, em minha experiência pessoal, precisei fornecer suporte a um novo colaborador para configurar seu ambiente de desenvolvimento. Haviam várias documentações sobre o mesmo procedimento, mas em plataformas distintas e cada uma redigida de forma única. Isso resultava em instruções conflitantes. As documentações estavam distribuídas da seguinte forma:
- Uma no Google Docs.
- Duas na página de wiki do GitLab.
- Uma no Confluence.
Como mencionado, as documentações tornaram-se confusas ao longo do tempo, pois os autores focaram apenas na entrega inicial, raramente atualizando-as posteriormente. Esse cenário beira o caos.
Diante desses problemas, decidi estudar a filosofia do Docs-as-code para encontrar uma solução definitiva para o gerenciamento da documentação nos meus projetos. O Docs-as-code visa unificar a fonte da documentação, em vez de dispersá-la. Ele centraliza todo o conteúdo, facilitando o acesso e contribuição das equipes.