Documentação de software

Documentação de software é texto escrito ou ilustração que acompanha o software de computador ou está incorporado no código-fonte. A documentação explica como o software funciona ou como usá-lo e pode significar coisas diferentes para pessoas em funções diferentes.

A documentação é uma parte importante da engenharia de software. Os tipos de documentação incluem:

• Requisitos – Declarações que identificam atributos, capacidades, características ou qualidades de um sistema. Esta é a base para o que será ou foi implementado.
• Arquitetura/Design – Visão geral do software. Inclui relações com um ambiente e princípios de construção a serem usados na concepção de componentes de software.
• Técnico – Documentação de código, algoritmos, interfaces e APIs.
• Usuário final – Manuais para o usuário final, administradores de sistema e pessoal de suporte.
• Marketing – Como comercializar o produto e análise da demanda do mercado.

Tipos

Documentação de requisitos

A documentação de requisitos é a descrição do que um determinado software faz ou deverá fazer. É usado durante todo o desenvolvimento para comunicar como o software funciona ou como pretende operar. Também é usado como um acordo ou como base para um acordo sobre o que o software fará. Os requisitos são produzidos e consumidos por todos os envolvidos na produção de software, incluindo: usuários finais, clientes, gerentes de projeto, vendas, marketing, arquitetos de software, engenheiros de usabilidade, designers de interação, desenvolvedores e testadores.

Os requisitos vêm em uma variedade de estilos, notações e formalidades. Os requisitos podem ser semelhantes a objetivos (por exemplo, ambiente de trabalho distribuído), próximos ao design (por exemplo, compilações podem ser iniciadas clicando com o botão direito em um arquivo de configuração e selecionando a opção 'construir&# 39; function) e qualquer coisa intermediária. Eles podem ser especificados como declarações em linguagem natural, como figuras desenhadas, como fórmulas matemáticas detalhadas ou como uma combinação de todos eles.

A variação e a complexidade da documentação de requisitos fazem dela um desafio comprovado. Os requisitos podem ser implícitos e difíceis de descobrir. É difícil saber exatamente quanto e que tipo de documentação é necessária e quanto pode ser deixado para a documentação de arquitetura e projeto, e é difícil saber como documentar requisitos considerando a variedade de pessoas que deverão ler e usar a documentação. Assim, a documentação de requisitos é muitas vezes incompleta (ou inexistente). Sem a documentação de requisitos adequada, as alterações de software tornam-se mais difíceis — e, portanto, mais propensas a erros (diminuição da qualidade do software) e demoradas (caras).

A necessidade de documentação de requisitos normalmente está relacionada à complexidade do produto, ao impacto do produto e à expectativa de vida do software. Se o software for muito complexo ou desenvolvido por muitas pessoas (por exemplo, software para celular), os requisitos podem ajudar a comunicar melhor o que deve ser alcançado. Se o software for crítico para a segurança e puder ter um impacto negativo na vida humana (por exemplo, sistemas de energia nuclear, equipamentos médicos, equipamentos mecânicos), muitas vezes será necessária uma documentação de requisitos mais formal. Se se espera que o software dure apenas um mês ou dois (por exemplo, aplicações muito pequenas para telemóveis desenvolvidas especificamente para uma determinada campanha), poderá ser necessária muito pouca documentação de requisitos. Se o software for uma primeira versão que será posteriormente desenvolvida, a documentação de requisitos será muito útil ao gerenciar a alteração do software e verificar se nada foi quebrado no software quando ele foi modificado.

Tradicionalmente, os requisitos são especificados em documentos de requisitos (por exemplo, usando aplicativos de processamento de texto e aplicativos de planilhas). Para gerenciar o aumento da complexidade e a natureza mutável da documentação de requisitos (e da documentação de software em geral), são defendidos sistemas centrados em banco de dados e ferramentas de gerenciamento de requisitos para fins especiais.

No desenvolvimento ágil de software, os requisitos são frequentemente expressos como histórias de usuários acompanhadas de critérios de aceitação.

Documentação do projeto de arquitetura

A documentação de arquitetura (também conhecida como descrição de arquitetura de software) é um tipo especial de documento de design. De certa forma, os documentos de arquitetura são a terceira derivada do código (o documento de design é a segunda derivada e os documentos de código são a primeira). Muito pouco nos documentos de arquitetura é específico do código em si. Estes documentos não descrevem como programar uma rotina específica, ou mesmo por que essa rotina específica existe na forma que existe, mas apenas estabelecem os requisitos gerais que motivariam a existência de tal rotina. Um bom documento de arquitetura tem poucos detalhes, mas muitas explicações. Pode sugerir abordagens para projetos de nível inferior, mas deixa os estudos reais de exploração comercial para outros documentos.

Outro tipo de documento de design é o documento de comparação, ou estudo comercial. Isso geralmente assumia a forma de um white paper. Centra-se num aspecto específico do sistema e sugere abordagens alternativas. Pode ser na interface do usuário, no código, no design ou até mesmo no nível arquitetônico. Descreverá qual é a situação, descreverá uma ou mais alternativas e enumerará os prós e os contras de cada uma. Um bom documento de estudo comercial exige muita pesquisa, expressa sua ideia com clareza (sem depender muito de jargões obtusos para deslumbrar o leitor) e, o mais importante, é imparcial. Deve explicar de forma honesta e clara os custos de qualquer solução que ofereça da melhor forma. O objetivo de um estudo comercial é conceber a melhor solução, em vez de defender um ponto de vista específico. É perfeitamente aceitável não declarar qualquer conclusão ou concluir que nenhuma das alternativas é suficientemente melhor do que a linha de base para justificar uma mudança. Deve ser abordado como um empreendimento científico, não como uma técnica de marketing.

Uma parte muito importante do documento de design no desenvolvimento de software empresarial é o Documento de Design de Banco de Dados (DDD). Ele contém elementos de design conceitual, lógico e físico. O DDD inclui as informações formais que as pessoas que interagem com o banco de dados precisam. O objetivo de prepará-lo é criar uma fonte comum para ser usada por todos os jogadores da cena. Os potenciais usuários são:

• Designer de banco de dados
• Desenvolvedor de banco de dados
• Administrador de banco de dados
• Designer de aplicações
• Desenvolvedor de aplicativos

Ao falar sobre Sistemas de Banco de Dados Relacionais, o documento deve incluir as seguintes partes:

• Entidade - Esquema de Relacionamento (aumentado ou não), incluindo as seguintes informações e suas definições claras:
  • Conjuntos de Entidade e seus atributos
  • Relacionamentos e seus atributos
  • Chaves para cada conjunto de entidades
  • Atributo e Tuple restrições baseadas
• Schema relacional, incluindo as seguintes informações:
  • Tabelas, atributos e suas propriedades
  • Vistas
  • Restrições como chaves primárias, chaves estrangeiras,
  • Cardinalidade de restrições referenciais
  • Política de Cascata para restrições referenciais
  • Chaves primárias

É muito importante incluir todas as informações que serão utilizadas por todos os atores da cena. Também é muito importante atualizar os documentos, pois qualquer alteração ocorre também no banco de dados.

Documentação técnica

É importante que os documentos de código associados ao código-fonte (que podem incluir arquivos README e documentação da API) sejam completos, mas não tão detalhados que se tornem excessivamente demorados ou difíceis de mantê-los. Vários guias de documentação de instruções e visão geral são comumente encontrados específicos para o aplicativo de software ou produto de software que está sendo documentado pelos criadores de API. Esta documentação pode ser usada por desenvolvedores, testadores e também usuários finais. Hoje, muitas aplicações de ponta são vistas nas áreas de energia, energia, transporte, redes, aeroespacial, segurança, proteção, automação industrial e uma variedade de outros domínios. A documentação técnica tornou-se importante nessas organizações, pois o nível básico e avançado de informações pode mudar ao longo do tempo com mudanças na arquitetura.

Documentos de código geralmente são organizados em um estilo de guia de referência, permitindo que um programador procure rapidamente uma função ou classe arbitrária.

Documentação técnica incorporada no código-fonte

Muitas vezes, ferramentas como Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText ou Universal Report podem ser usadas para gerar automaticamente os documentos de código, ou seja, extraem os comentários e contratos de software, quando disponíveis, a partir do código-fonte e criam manuais de referência em formatos como arquivos de texto ou HTML.

A ideia de gerar documentação automaticamente é atraente para os programadores por vários motivos. Por exemplo, por ser extraído do próprio código-fonte (por exemplo, através de comentários), o programador pode escrevê-lo referindo-se ao código, e utilizar as mesmas ferramentas utilizadas para criar o código-fonte para fazer a documentação. Isso torna muito mais fácil manter a documentação atualizada.

Uma possível desvantagem é que somente programadores podem editar esse tipo de documentação, e depende deles atualizar a saída (por exemplo, executando um cron job para atualizar os documentos todas as noites). Alguns caracterizariam isso como uma vantagem e não como uma desvantagem.

Programação alfabetizada

O respeitado cientista da computação Donald Knuth observou que a documentação pode ser um processo de reflexão tardia muito difícil e defendeu uma programação alfabetizada, escrita no mesmo horário e local que o código-fonte e extraída por meios automáticos. As linguagens de programação Haskell e CoffeeScript possuem suporte integrado para uma forma simples de programação alfabetizada, mas esse suporte não é amplamente utilizado.

Programação elucidativa

A Programação Elucidativa é o resultado de aplicações práticas da Programação Alfabetizada em contextos reais de programação. O paradigma Elucidativo propõe que o código-fonte e a documentação sejam armazenados separadamente.

Muitas vezes, os desenvolvedores de software precisam ser capazes de criar e acessar informações que não farão parte do arquivo de origem em si. Tais anotações geralmente fazem parte de diversas atividades de desenvolvimento de software, como code walks e porting, onde o código-fonte de terceiros é analisado de forma funcional. As anotações podem, portanto, ajudar o desenvolvedor durante qualquer estágio de desenvolvimento de software onde um sistema de documentação formal impediria o progresso.

Documentação do usuário

Diferentemente dos documentos de código, os documentos de usuário simplesmente descrevem como um programa é usado.

No caso de uma biblioteca de software, os documentos de código e os documentos de usuário podem, em alguns casos, ser efetivamente equivalentes e valer a pena conjuntá-los, mas para uma aplicação geral isso nem sempre é verdade.

Normalmente, a documentação do usuário descreve cada recurso do programa e auxilia o usuário na realização desses recursos. É muito importante que os documentos do usuário não sejam confusos e que estejam atualizados. Os documentos do usuário não precisam ser organizados de nenhuma maneira específica, mas é muito importante que tenham um índice completo. Consistência e simplicidade também são muito valiosas. A documentação do usuário é considerada um contrato que especifica o que o software fará. Os escritores de API são muito bem-sucedidos em escrever bons documentos de usuário, pois estão bem cientes da arquitetura de software e das técnicas de programação usadas. Veja também redação técnica.

A documentação do usuário pode ser produzida em vários formatos on-line e impressos. Entretanto, existem três maneiras amplas pelas quais a documentação do usuário pode ser organizada.

1. Tutorial: Uma abordagem tutorial é considerada a mais útil para um novo usuário, em que eles são guiados através de cada etapa de realização de tarefas particulares.
2. Temática: Uma abordagem temática, onde os capítulos ou secções se concentram em uma determinada área de interesse, é de uso mais geral para um usuário intermediário. Alguns autores preferem transmitir suas ideias através de um artigo baseado em conhecimento para facilitar as necessidades do usuário. Esta abordagem é geralmente praticada por uma indústria dinâmica, como a tecnologia da informação.
3. Lista ou Referência: O tipo final de princípio de organização é aquele em que comandos ou tarefas são simplesmente listados alfabeticamente ou logicamente agrupados, muitas vezes através de índices cruzados. Esta última abordagem é de maior uso para usuários avançados que sabem exatamente que tipo de informação eles estão procurando.

Uma reclamação comum entre os usuários em relação à documentação de software é que apenas uma dessas três abordagens foi adotada, quase excluíndo as outras duas. É comum limitar a documentação de software fornecida para computadores pessoais à ajuda online que fornece apenas informações de referência sobre comandos ou itens de menu. O trabalho de orientar novos usuários ou ajudar usuários mais experientes a tirar o máximo proveito de um programa é deixado para editores privados, que geralmente recebem assistência significativa do desenvolvedor do software.

Composição da documentação do usuário

Como outras formas de documentação técnica, uma boa documentação do usuário se beneficia de um processo organizado de desenvolvimento. No caso da documentação do usuário, o processo, como ocorre comumente na indústria, consiste em cinco etapas:

1. Análise do usuário, a fase de pesquisa básica do processo.
2. Planejamento, ou a fase de documentação real.
3. Projeto de revisão, uma fase auto-explicativa onde o feedback é procurado no rascunho composto na etapa anterior.
4. Teste de usabilidade, pelo qual a usabilidade do documento é testada empiricamente.
5. Editar, o passo final em que as informações coletadas nas etapas três e quatro são usadas para produzir o rascunho final.

Documentação de marketing

Para muitas aplicações é necessário ter alguns materiais promocionais para incentivar os observadores casuais a passarem mais tempo aprendendo sobre o produto. Esta forma de documentação tem três finalidades:

1. Para excitar o usuário potencial sobre o produto e incutir neles um desejo de se envolver mais com ele.
2. Para informá-los sobre o que exatamente o produto faz, de modo que suas expectativas estão em linha com o que eles estarão recebendo.
3. Para explicar a posição deste produto em relação a outras alternativas.

Controvérsia sobre documentação e desenvolvimento ágil

"A resistência à documentação entre os desenvolvedores é bem conhecida e não precisa de ênfase." Esta situação é particularmente prevalente no desenvolvimento ágil de software porque estas metodologias tentam evitar quaisquer atividades desnecessárias que não tragam valor diretamente. Especificamente, o Manifesto Ágil defende a valorização de “software funcional em vez de documentação abrangente”, o que poderia ser interpretado cinicamente como “Queremos gastar todo o nosso tempo codificando”. Lembre-se de que programadores reais não escrevem documentação.

Uma pesquisa entre especialistas em engenharia de software revelou, no entanto, que a documentação não é de forma alguma considerada desnecessária no desenvolvimento ágil. No entanto, reconhece-se que existem problemas motivacionais no desenvolvimento e que podem ser necessários métodos de documentação adaptados ao desenvolvimento ágil (por exemplo, através de sistemas de reputação e gamificação).