O que exatamente compreende 'Documentação'?

Quando dizemos 'documentação' para um produto de software, o que isso inclui e o que não deve incluir?

Por exemplo, uma pergunta recente perguntou se os comentários são considerados documentação?

Mas há muitas outras áreas para as quais essa pergunta também é válida, algumas mais óbvias que outras:

• Manuais (obviamente)
• Notas de versão?
• Tutoriais
• Comentários
• Alguma outra?

Onde está a linha desenhada. Por exemplo, se 'tutorial' é documentação, é documentação de 'vídeo tutorial' ou é outra coisa?

Geralmente, algo no software não é 'feito' até que seja implementado, testado e documentado. Daí esta pergunta, que coisas devemos considerar como parte da documentação para considerar algo "feito".

_{As perguntas inspiram-se nos recentes comentários dos clientes em nossa conferência, indicando que nosso documento precisava de mais 'amostras', que anteriormente não tínhamos sido tão boas em considerar quanto deveríamos ter.}

_{Público-alvo: desenvolvedores de software que usam nosso banco de dados, linguagens de programação e ferramentas associadas (como clientes administrativos ao referido banco de dados)}

O objetivo da documentação é descrever e explicar o produto de software, para que você possa definir a documentação como o conjunto de artefatos que contribuem para essa descrição ou explicação. Você provavelmente não consideraria ações relacionadas como parte da documentação: por exemplo, um curso de treinamento de uma semana não é documentação, mas os materiais do curso; um bate-papo de cinco minutos no quadro branco não é documentação, mas uma imagem do quadro branco.

Mantendo o objetivo (explicando o software) em mente, a documentação termina quando o cliente está satisfeito com a explicação : assim como o software termina quando o cliente está satisfeito com o software. Lembre-se de que o cliente para a documentação nem sempre é o mesmo que paga pelo software: pessoal de suporte, testadores, vendedores e outros precisarão entender o que o software faz e como funciona.

Isso ajuda a entender onde está o seu limite para o que deve ser incluído na documentação. Usando o "leitor" como uma abreviação conveniente, embora aceitemos que vídeos ou áudio possam ser incluídos: qualquer coisa que ajude o leitor a obter as informações necessárias sobre o software é a documentação que eles podem usar, tudo o resto não é. Se o seu cliente precisar de orientações detalhadas de todos os seus casos de uso, isso deverá fazer parte da documentação. Seus desenvolvedores provavelmente precisam de código fonte, informações sobre o repositório de controle de versão e instruções de compilação: isso é documentação para eles, mas, conforme descrito acima, não faria parte da documentação do cliente.

Eu acho que você tirou a parte errada da sua conversa em uma conferência. As modernas metodologias de desenvolvimento de software defendem que a equipe de desenvolvimento deve trabalhar em estreita colaboração com seus clientes (ou com o proprietário do produto que atua como proxy do cliente). Para todo o trabalho entregue, a definição de "concluído" é algo que é negociado entre a equipe e seu cliente e é feito de forma recorrente à medida que o software está sendo desenvolvido.

O problema com o qual você se deparou é que havia uma desconexão entre o que você supunha que o cliente precisava e o que eles esperavam que você entregasse, e no final você recebeu a surpresa "ei, onde estão todas as amostras"?

Quanto à documentação ... bem, é praticamente tudo o que você listou e talvez mais algumas coisas que você não fez. Mas ninguém pode lhe dizer quanta documentação o seu projeto precisa. Cada projeto é diferente e depende da sua equipe, do proprietário do produto e de seus clientes determinar o nível e o tipo de documentação necessária para o seu projeto.

Alguns fatores que entrariam em jogo:

• Você está desenvolvendo o software v1.0 e eles estão migrando para outros projetos ou esse é um projeto em andamento a longo prazo? Os comentários / documentos de design tornam-se muito mais importantes neste último caso. Por outro lado, se seu cliente é uma loja de donuts e você está escrevendo um site para eles que nunca verá ... bem, acho que a documentação do código é boa, mas não tão importante.
• Você está desenvolvendo um jogo ou software para celular que controla o monitor de batimentos cardíacos em um hospital. Adivinha qual deles terá a definição de "concluído" que possui muito mais documentação?
• Seus clientes são usuários finais típicos ou são outros desenvolvedores? Você tem uma API / SDK que está expondo?
• Qual é o nível de conhecimento de seus clientes? Isso afeta a escolha do tutorial em vídeo x material escrito vs. algum tipo de aplicativo tutorial interativo
• Seus clientes se preocupam com o que mudou de versão para versão. Alguns fazem. A maioria não. Para poucos, é a lei (ou quase isso) que importa.

Documentação é um material destinado a ser lido sem modificá-lo.

Eu acho que você não pode dar errado com a definição baseada em propósitos ... mas apenas se você definir propósitos corretamente.

• ^{Definir corretamente o objetivo da documentação não é tão simples. A distinção direta (ingênua, se você desejar) que naturalmente vem à mente é que a documentação é tudo o que se destina à leitura - enquanto, para comparação, o código é qualquer coisa destinada à execução do computador . Parece bom na superfície, não é? mas fica realmente muito feio quando você se aprofunda.
   
  O bom é que o código leva em consideração as preocupações de legibilidade, além da correção da execução - isso torna a distinção de "legibilidade" bastante inútil na definição da documentação.
   
  As mesmas amostras que você mencionou mostram o que há de errado com isso. Os clientes normalmente esperam que eles sejam claramente escritos eexecutar corretamente. Comprometer a legibilidade ou a correção pode trazer uma série de reclamações dos clientes. A distinção ingênua não ajuda a descobrir se as amostras são código ou documentação.
   
  Usar distinção ingênua ficará ainda mais confuso se você imaginar trabalhar com código aberto . Você baixa, constrói e executa - você não lê, é apenas o código, certo? Espere, as coisas de alguma forma deram errado e você acessa o código para ler o que está acontecendo lá ... ei, você lê, não executa - essa documentação é agora? E, finalmente, você encontra um bug na fonte e o corrige - agora esse é realmente o código, não é algo normalmente chamado de documentação, não importa o quão cuidadosamente você o leia para fazer essa correção.}

Para as 'amostras' que você fornecerá, a distinção de leitura e não modificação pode se tornar bastante importante.

Olha, se alguma amostra falhar quando executada inalterada, no ambiente de referência documentado, é seu bug - bug na documentação, que você precisa aceitar e corrigir, tudo bem.

Agora, se houver um problema com amostra ou ambiente modificado, a culpa não é mais sua - não quero dizer nenhum erro na documentação, pois os documentos não se destinam à modificação. Qualquer ajuda que você forneça aos usuários em um caso como esse seria da categoria de suporte, não uma correção de bug.

Qualquer coisa que responda a uma pergunta "como faço para ..." é documentação.

Para desenvolvedores, isso significa especificações de requisitos ("como sei o que escrever"), documentos de design ("como abordo meus requisitos"), matrizes de rastreabilidade ("como sei que meu design atende a todos os meus requisitos"), planos de teste ("como sei se meu código funciona"), testes de unidade ("como sei se salvou o requisito X"), comentários em linha ("como garantir que o próximo schlub pobre entenda por que escrevi isso?" caminho "), instruções de implantação (" como empacotar este produto para instalação ") etc.

Para os usuários, que os manuais meios de utilizador ( "como faço para usar o software"), tutoriais ( "como faço para usar este recurso específico"), notas de lançamento ( "como eu sei o que bugs foram corrigidos / novos erros características foram adicionado ") etc.