Qual nível de documentação você espera que lhe seja fornecido pelos desenvolvedores?

Realmente o titulo diz tudo.

Às vezes, pode acabar que o desenvolvimento e a TI estão em desacordo com esse tipo de coisa. Qual o nível de documentação que você espera quando espera instalar, corrigir, manter, iniciar, interromper e diagnosticar uma solução em execução em um ou mais servidores?

Todas essas coisas devem ser documentadas em detalhes, embora, quando a operação for padrão para o sistema operacional, servidor de aplicativos, servidor da Web, etc., você possa assumir que as operações de TI as pessoas sabem como fazer isso.

Instalação: documente tudo sobre como está instalado e configurado, incluindo como saber se está funcionando corretamente.

Conte-nos sobre a arquitetura, especialmente sobre a comunicação entre vários componentes da solução (por exemplo, intervalo de portas - os mecanismos RPC costumam usar um intervalo de portas - precisamos saber qual é o intervalo e quando o aplicativo pode ficar sem portas).

Correção: documente qualquer coisa específica do aplicativo - o que precisa ser desligado antes da correção e quaisquer ações de acompanhamento após a correção (caches, índices, proxies que talvez precisem ser limpos ou reconstruídos).

Manutenção: documente como é a operação normal e anormal - quais filas e outras coisas devem ser monitoradas e qual é o intervalo normal delas.

Diga-nos como gerenciar os dados - especialmente tabelas e arquivos que crescem sem limites (por exemplo, arquivos de log e históricos de transações). Como elas devem ser eliminadas e qual o impacto da remoção de entradas antigas? (nos relatórios etc).

Diga-nos como executar ações padrão de gerenciamento "comercial como de costume" / na vida útil - isso pode incluir ou modificar contas de usuário, por exemplo.

Conte-nos sobre outras ações de gerenciamento regulares que possam ser necessárias (por exemplo, quais certificados são usados ​​e o que fazer quando expiram).

Para todas as alterações, diga-nos como revertê-las (nem todas as alterações são bem-sucedidas). E diga-nos que você testou os planos de reversão!

Diagnóstico: Documente os formatos e locais dos arquivos de log e TODAS as mensagens de erro do aplicativo que possam aparecer, dizendo o que significa a mensagem de erro está errada e o que pode ser necessário alterar para corrigi-la. Nunca use a mesma mensagem de erro para dois eventos diferentes.

Abatido e inicializado: Como, em que ordem, quaisquer procedimentos especiais (por exemplo, permitir que os servidores drenem as conexões antes de desligá-las).

Discordo totalmente de que a melhor maneira de fazer isso é lançar o aplicativo por cima do muro e permitir que o pessoal de TI trabalhe no que é necessário. A documentação operacional (e, em geral, os recursos de gerenciabilidade do aplicativo) precisa ser pensada com antecedência.

Uma pergunta a seguir seria: o que acontece quando (e não se) os desenvolvedores não fornecem documentação suficiente?

Eu recomendo que a TI tenha a capacidade de inserir relatórios de defeitos no software, usando qualquer sistema de rastreamento de defeitos usado pelos desenvolvedores. Dessa forma, se eles não disserem, por exemplo, que os arquivos em uma pasta específica precisam ser removidos e que apenas uma semana deve ser mantida, você pode inserir um defeito dizendo "aplicativo preenche o disco com arquivos de log" "e sugira que trabalhem com a TI em uma técnica documentada para limpar essa pasta.

Minha lista de requisitos para documentação seria (não em nenhuma ordem específica):

(documentação em :)

• todas as opções de linha de comando
• todos os estados de saída e valores de retorno
• mensagens de log (não tanto o conteúdo, mas explicando os campos, se não for configurável)
• sintaxe de configuração
• alterna nos arquivos de configuração
• uso de memória
• é rosqueado ou bifurcado
• quais são os sinais nos quais o servidor reage
  • existe algum sinal que não reinicie o servidor, mas faça com que ele releia a configuração
  • como se comporta? (ele espera que os processos / threads existentes terminem com a configuração antiga. Ele os mata, ...)
• o que acontece no desligamento impuro (especialmente se for algum tipo de serviço / servidor de persistência)
• ele faz logon através de chamadas fornecidas pelo sistema ou faz logon com algo escrito por si só ( eca para apache e log de acesso - eu claramente prefiro ferramentas integradas para log)
• Pronto para IPv4 e IPv6 se for um serviço de rede
• documentação no tronco e documentação em uma versão específica
  • nada é tão ruim quanto configurar algo por horas apenas para descobrir que será ignorado porque a opção de configuração está disponível apenas no tronco
• qual opção de configuração é válida em qual versão (disponível desde: v1.0, obsoleta desde: v1.2 ou algo parecido)

Documentação como esta são exemplos de boa documentação:

• http://httpd.apache.org/docs/2.2/
• http://www.postgresql.org/docs/8.3/static/index.html

Eu consideraria uma documentação como esta cheia de falhas:

• http://tomcat.apache.org/tomcat-6.0-doc/index.html

Além disso, o FreeBSD Handbook é um ótimo exemplo de documentação e a abordagem do OpenBSD. Eles expulsam coisas que não estão devidamente documentadas.

EDIT: esta lista não é de forma alguma completa, são apenas as coisas básicas que imediatamente me vieram à mente. Além disso, a documentação deve ser bem legível, não apenas algo que se parece com alguém que vomitou .

Em resumo, espero a documentação especificada e contratada.

Muitas vezes esse detalhe crítico é deixado de fora de um acordo. O usuário final espera e quer de graça, é claro. Bons desenvolvedores corrigirão essa supervisão no início do processo e definirão as expectativas, incluindo um requisito de preço e tempo.

Acredito que a TI precisa se comunicar com os desenvolvedores que tipo de documentação é necessária. A melhor maneira de fazer isso é se o desenvolvimento fornecer versões de pré-lançamento (ou versões de iteração) de uma solução para a TI jogar e testar, para que a TI possa responder com o que for necessário.

Criar notas de versão adequadas com um aplicativo seria um bom começo. Se houver alterações no comportamento atual da versão, quaisquer observações do controle de qualidade sobre alterações nas dependências ou comportamentos de iniciar / parar, alterações no carregamento de servidores ou bancos de dados dependentes etc.

@ Spike (Ainda não posso comentar as respostas ..)

Os implementadores de TI (a função variará de acordo com o tipo e tamanho da empresa) devem trabalhar de forma consistente para obter o seguinte:

• Requisitos mínimos para instalação / rotatividade - em outras palavras, a TI não pode ser passiva e espera que os desenvolvedores "saibam" quais informações são necessárias no momento da instalação / rotatividade. Descobri que muitas vezes há considerável confusão / desacordo na TI quanto ao que constitui a documentação adequada de um aplicativo. O Dev entende os requisitos (esperamos) e a equipe de TI deve procurar o que - no mínimo - é necessário.

• Um procedimento de instalação / rotatividade - nas configurações da empresa, você pode chamar isso de Controle ou Governança de Mudanças, mas é essencialmente um ciclo de revisão padrão em que a TI se senta com a instalação superior PRI Dev para obter um resumo sobre o produto e suas necessidades.

Instalar um aplicativo não é diferente de estrear uma produção teatral. Antes que a cortina suba, o diretor (desenvolvedor principal) se reúne repetidamente com a equipe de produção do palco (implementadores de TI) para garantir que tudo esteja "perfeito" para a noite de abertura (instalação pública).

Você não pode alterar a persona Dev (por que você gostaria de mudar?), Mas pode apontar para seu objetivo compartilhado de um aplicativo fantástico que é extremamente rápido para todos os usuários. Seus requisitos de documentos de consenso são apenas uma das coisas necessárias para garantir isso.