Documentação é Código

Todos os produtos de desenvolvimento de software, sejam eles criados por uma pequena equipe ou por uma grande corporação, exigem alguma documentação relacionada e os difetentes tipos de documentos são criados ao longo de todo o ciclo de vida de desenvolvimento de software (SDLC).

Os métodos Àgeis não requerem documentações abrangentes no início - Software funcional em vez de documentação abrangente, logo a ideia é produzir documentação com informações essenciais para avançar quando fizer mais sentido.

Michael Nygard, em uma publicação de 2011, Os métodos ágeis não se opõem à documentação, apenas à documentação sem valor.

Documentos que auxiliam a própria equipe podem ter valor, mas somente se estiverem atualizados. Documentos grandes nunca são mantidos atualizados.

Documentos pequenos e modulares têm pelo menos uma chance de serem atualizados.

No cenário de desenvolvimento ágil e de constante inovação tecnológica, a relação entre o código e documentação para o usuário e desenvolvedores — é frequentemente considerada um ponto crítico.

Em uma análise simples, podemos adotar boas práticas de desenvolvimento e da documentação, sendo possível evitar essa defasagem, mantendo a documentação sempre alinhada com as alterações.

As aplicações e documentações, quando mantidas de acordo com padrões e processos adequados, não apresentam defasagem em seu conteúdo e de suas alterações.

Linguagem Leve¶

A "linguagem de marcação leve" que permite formatar texto simples, é destacada pela simplicidade e a facilidade de aprendizado do `Markdown`, que o diferencia de outros métodos de formatação como editores WYSIWYG ("What You See Is What You Get", ou "o que você vê é o que você obtém").

• Markdown é uma ferramenta versátil e poderosa para formatação de texto, adequada para uma ampla gama de aplicações, que vão desde a criação de simples notas até a produção de livros e documentação técnica;
• A simplicidade e a facilidade de aprendizado do Markdown são vantagens importantes em comparação com outras ferramentas de formatação;
• O conceito de "processadores Markdown" para converter texto formatado em HTML é crucial para entender como Markdown funciona;
• A capacidade de estender a sintaxe básica do Markdown com funcionalidades adicionais aumenta a flexibilidade e aplicabilidade da ferramenta;
• O guia serve como uma referência abrangente, adequado para iniciantes e usuários experientes, e fornece exemplos práticos e recursos úteis;
• Este texto da um convite para experimentar o Markdown através do editor online Dillinger, que mostra uma pré-visualização do texto formatado;
• O texto formatado em Markdown é armazenado em arquivos com extensão .md ou .markdown;
• Markdown pode ser usado para uma ampla variedade de finalidades, incluindo websites, documentos, notas, livros, apresentações, e-mails e documentação;
• Plataformas de criação de websites (blot.im, Jekyll), aplicativos de escrita de documentos (iA Writer, Ulysses, MarkdownPad), aplicativos de anotações (Simplenote, Bear, Boostnote), serviços de publicação de livros (Leanpub) e ferramentas para criação de apresentações (Remark, Cleaver);
• A flexibilidade e a portabilidade do Markdown são destacadas como vantagens significativas;
• Folha de Dicas para o Markdown;

Estrutura do Diretório do Portifólio¶

Escrita da Documentação¶

NÃO SE DEVE escrever as documentações nas ferrametas Office-Microsoft, DEVEmos escrever da mesma forma, que escrevemos CÓDIGO.

• Ferramentas centradas no desenvolvedor para documentação são freqüentemente chamadas de Docs-as-Code. Tratar documentos como código geralmente significa fazer o seguinte:

• Trabalhar em arquivos de texto simples;

• Usar um gerador de site estático (SSG);
• Trabalhar com arquivos por meio de um editor de texto (VS Code);
• Armazenamento de documentos em um repositório de controle de versão;
• Automatizar o processo de construção do site ou Portable Document Format (PDF) com entrega contínua;
• Com esta definição de documentação, nós podemos expressar alguns princípios:
  • Conhecimento que é de interesse por uma grandes período de Tempo DEVE ser documentado;
  • Conhecimento que é de interesse para um amplo número de pessoas DEVE ser documentado;
  • Conhecimento que é valioso ou crítico DEVE ser documentado;

Em vez de criar a documentação em um sistema separado, os analistas de requisitos e desenvolvedores simplesmente adicionam o documento no mesmo projeto em repositórios diferentes ou no mesmo repositório do código, através do uso de markdown. Esse local garante que qualquer pessoa que esteja usando o código também possa encontrar a documentação.

Qualquer um pode ler a documentação diretamente no código-fonte do Markdown ou podem lê-la exibida em um navegador. Com a Documentação como Código, os desenvolvedores tratam a documentação como parte integrante do sistema, melhoram as mensagens de commit. A documentação, junto com o código, é construída e implantada como parte de um pipeline.

Escrever documentação é entediante e chato, mas de suma importancia. Alguns até pensam que escrever documentação é um esforço infrutífero, visto que os desenvolvedores acham que seu código incrível é autodocumentado. Portanto, um software bem documentado é normalmente uma exceção.

Resumindo, tratar os documentos como código significa usar os mesmos sistemas, processos e fluxos de trabalho com os documentos que você faz com o código de programação.

Hoje, esta estrutura é utilizada para se referir de forma mais ampla a uma abordagem arquitetônica para construção de sites.

• Não há necessidade de se preocupar com vulnerabilidades de servidores ou bancos de dados;
• A hospedagem de arquivos estáticos é barata;
• Cada implantação é um instantâneo completo do site. Isto ajuda a garantir um versão consistente do site globalmente.
• Seu texto reside em um sistema de controle de versão, como o Git.
• Minha versão segue a versão do Código.

Entre os diversos SSG(Static Site Generatos), foram escolhidos o HUGO e o MkDocs.Como seria uma coisa muito simples, não requerendo conhecimento específico, escolhi o MkDocs por ser mais rápido, simples e gerador voltado para a construção de documentação de projetos. Orientei a TODOS que tivessem um repositório separado de documentação, o que facilitaria a automatização e unificação dos mesmos.

Documentação Técnica no Desenvolvimento de Software¶

É o termo genérico que abrange todos os documentos e materiais escritos que tratam do desenvolvimento de produtos de software. A documentação de qualquer sistema/produto, consiste em:

flowchart TD
A(Desenvolver) --> B(Controle</br>de versão)
B              --> C(Pull Request)
C              --> D(Pipeline</br>Código) & E(Pipeline</br>Documentação)
D & E          --> F(Aprovação)
F              --> G(Geração Container) & H(Construção Automatizada)
H              --> I(Ativos estáticos)
I              --> J(Implantação atômica)
J              --> K(Pré-render e invalidar cache)
K              --> L(Entrega e </br>Distribuição de</br> conteúdo)

Vantagens¶

Nosso manual é novo e mantê-lo relevante é uma parte importante do trabalho de todos. É uma parte vital de quem somos e de como nos comunicamos. Estabelecemos esses processos porque vimos estes benefícios:

• Equilíbrio entre nenhuma documentação e documentação excessiva;
• Ler é muito mais rápido do que ouvir;
• A leitura é assíncrona, você não precisa interromper alguém ou esperar que ele fique disponível;
• A retenção é melhor se as pessoas souberem no que estão se metendo antes de aderirem;
• A integração é mais fácil se você encontrar todas as informações relevantes explicadas;
• O trabalho em equipe será mais fácil se você puder ler como outras partes que trabalham;
• Discutir as mudanças é mais fácil se você puder ler qual é o processo atual;
• Comunicar a mudança é mais fácil se você puder apenas apontar para a diferença;
• Todos podem contribuir propondo uma mudança por meio de uma solicitação pull;

“Foco não é nada, foco é tudo"¶

Sou um defensor do foco no trabalho, na vida e na liderança. No entanto, o assunto tem uma nuance e profundidade que muitas pessoas não percebem. Para começar, a maioria das pessoas pensa que existe apenas um tipo de foco.

• Foco como substantivo: Geralmente se referem a ter um único objetivo. É algo estático, algo que você tem;

• Foco como verbo : não é apenas algo que você tem, é também algo que você faz. é um processo intenso, dinâmico, contínuo e iterativo;

• Temos que desenvolver e valorizar ambos os tipos de foco;

• A estratégia deliberada, onde os líderes desenvolvem uma visão clara e a mapeiam para objetivos de longo, médio e curto prazo (foco como substantivo) e estratégia emergente, onde as pessoas respondem a problemas e oportunidades imprevistas (foco como verbo);

Vamos ler? Greg McKeown - Essentialism: The Disciplined Pursuit of Less.

Markdown¶

É uma linguagem de marcação leve que você pode usar para adicionar elementos de formatação a documentos de texto sem formatação. Pode ser usado para tudo, desenvolvedores usam para criar sites, documentos, notas, livros, apresentações , mensagens de e-mail e documentação técnica. Arquivos contendo texto formatado em Markdown podem ser abertos usando virtualmente qualquer aplicativo. Se você decidir que não gosta do aplicativo Markdown que está usando no momento, pode importar seus arquivos Markdown para outro aplicativo Markdown.

Você pode criar texto formatado em Markdown em qualquer dispositivo que execute qualquer sistema operacional.Mesmo que o aplicativo que você esteja usando pare de funcionar em algum momento no futuro, você ainda poderá ler seu texto formatado em Markdown usando um aplicativo de edição de texto. Ou seja, markdown é uma maneira rápida e fácil de fazer anotações, criar conteúdo para um site e produzir documentos prontos para impressão.

• Modern Technical Writing: An Introduction to Software Documentation
• Docs Like Code: Collaborate and Automate to Improve Technical Documentation
• [Veja a nossa documentação]

Origem de Conhecimento¶

O conhecimento vem principalmente de conversas, durante o trabalho coletivo, como programação em pares, no máquina de café, por telefone ou por meio de bate-papo ou e-mails da empresa. O desenvolvimento de software tem tudo a ver com conhecimento e tomada de decisão.

• Conhecimento vem a partir de conversas com pessoas e experimentos com máquinas dentro a observável contexto.

Por que conhecimento é necessário?¶

• Que problema estamos tentando resolver? Todos deveriam saber disso a partir de agora?
• Falta de conhecimento manifesta dois custos:
  • Desperdiçado Tempo;
  • Decisões abaixo do ideal;
• O tero documentação viva tornou-se popular pela primeira vez no livro Specification by Example de Gojko Adzic. Vivendo documentação envolve uma definir de quatro princípios:

Fonte de Documentação¶

Site Estático x Dinâmico¶

Um site estático é uma combinação de HTML e CSS, que são os estilos e layouts aplicados a essas páginas, e JavaScript, uma linguagem de programação que define seu comportamento.Essas páginas são armazenadas como arquivos simples, que são servidos por um servidor web.

Um site dinâmico é mais complicado do que isso. Além da marcação, dos estilos e do comportamento, eles fazem mais coisas que nossos navegadores podem identificar. Por exemplo, se você está comprando algo online, é fácil entender que os preços e a disponibilidade desse item são recuperados dinamicamente a partir de alguns dados, geralmente armazenados em bancos de dados. Este processo de recuperar dados e processá-los antes de responder aos nossos navegadores como páginas da web contendo essas informações, é chamado de processamento do lado do servidor. Com a crescente popularidade dos sites baseados no servidor, surgiram suas vulnerabilidades

.

Quais são as vantagens de um sobre o outro?¶

Uma medida inteligente para evitar essas ameaças à segurança e, ao mesmo tempo, manter os benefícios dos sistemas de templates, foi a criação de Static Site Generators (SSGs), com eles, escrevemos dinamicamente e publicamos estaticamente.

Repositório Específicos para a Documentação (LIB)¶

Como uma BOA PRÁTICA, devemos ISOLAR os códigos de documentos, pois com o passar do tempo, o processo de check-out, branch, fetch e clone do código, aumentarão drasticamente o tempo. Lembre-se que documentação pode carregar imagens, gráficos,apresentações e pdfs que são importantes para o entendimento.

Treinamento em MkDocs¶

Fácil de instalar e usar, ótimos resultados com mínimo esforço,desenvolvidos ativo e de código aberto.

Iniciando a configuração do SITE Estático.

Documentação Contínua e Acompanhamento Ágil¶

A documentação de software deve ser tratada de forma contínua e DaC (Documentation as Code) e não como uma atividade pontual após o desenvolvimento do código.

Ao longo do ciclo de vida de um projeto, a documentação (tanto técnica quanto voltada para o usuário) deve ser constantemente atualizada, paralelamente ao progresso do desenvolvimento da aplicação.

A documentação "viva" é atualizada com a mesma frequência do código, garantindo que os engenheiros, gestores de qualidade e até mesmo os usuários, tenham acesso a informações precisas, em tempo real.

Em nossa aboardagem, trateremos de uma documentação contínua, que inclui:

• Documentação de código:

  • Commit Conventional (Comentários explicativos);
  • Testes e cobertura de testes;
  • Documentação de Código (Javadoc, Docstrings, JSDOC, PLDoc, RDoc,PHPDoc + phpDocumentor, GoDoc, Rustdoc)
  • Documentação de APIs (OAS, Swagger ou ReDoc);
  • Geradores de Dependencia e Vulnerabilidades;
  • Preenchimento de Templates durante o processo de Pull-Request;
  • Documentação de releases;

• Documentação do usuário, em um primeiro momento deverão ser utilizados as issues ou wits para a criação de épicos, pbis ou issues e mantidas na Wiki apenas o manual de operação da Aplicação.

  • Wiki
  • Planejamento do Projeto;
  • Documentação do usuário final orientada a processos;
  • Changelog (O que foi corrigido, adicionado e alterado nas releases);
  • Documentação técnica para manutenção;
  • Portifólio de Produtos
  • A documentação do Portifólio, será a unificação da Wiki (Manual do usuário - wiki2mkdocs);
  • Pull Request/Code Review efetuará a geração de chagelogs e republicação do Portifólio;
• Geração do Report Book;
• Geração de Catálogo de APIs por grupo;

Compreendendo seu público¶

Para escrever de forma eficaz para os usuários, é preciso entender quem eles são e o que desejam alcançar. É importante identificar os objetivos dos usuários para concentrar os esforços na documentação das informações mais relevantes. Uma persona de usuário é um personagem semificcional que representa o leitor ideal, incluindo seus objetivos, habilidades e conhecimentos. Mapas de jornada do usuário ajudam a entender as etapas que um usuário realiza ao interagir com um produto, juntamente com sua experiência em cada etapa.

Planejando sua documentação¶

Um caso de uso é um conjunto de tarefas necessárias para concluir um objetivo Os tipos de conteúdo incluem comentários de código, READMEs, documentação conceitual, documentação de introdução, documentação processual (tutoriais e guias de instruções) e referências de API. Um README resume uma coleção de código e contém informações básicas

A documentação conceitual ajuda os usuários a entender os conceitos e ideias por trás do serviço, evitando detalhes de implementação A documentação processual inclui tutoriais e guias de instruções, mostrando aos leitores como atingir um objetivo específico

Uma referência de API deve ser concisa e minimalista, apresentando informações importantes sobre a API

Elaboração de documentação¶

O título do documento deve resumir o objetivo da leitura Um esboço é uma maneira rápida de verificar a abordagem de um documento e permite discutir o conteúdo antes de investir muito tempo escrevendo

Longos conjuntos de parágrafos devem ser divididos com subtítulos, listas, amostras de código ou gráficos

A introdução deve ser escrita por último, descrevendo os principais temas e o que os leitores ganharão com a leitura

Editando documentação¶

Integrando código de exemplo¶

Amostras de código são essenciais para a documentação eficaz do desenvolvedor Amostras de código devem ser específicas, úteis e sustentáveis Amostras devem ser utilizáveis e extensíveis, indicando onde os leitores precisam inserir seus próprios dados

Adicionando conteúdo visual¶

O conteúdo visual (imagens, diagramas e vídeos) pode ser útil para explicar conceitos, mas é importante considerar sua acessibilidade, compreensão e desempenho

Vídeos devem ser curtos o suficiente para manter o interesse dos leitores, acessíveis e ter legendas