Pessoal, alguém poderia me citar boas referências (links, livros) sobre como documentar um software?
Sou um programador experiente mas não possuo muita experiência neste assunto.
Esse é um assunto que gera MUUUUUIIIITA (mas MUITA MESMO) controvérsia. Em algumas décadas 1,5 pra ser mais exato eu conhecia “A Fantástica Fábrica de Software”. Um lugar mágico onde uma linha de produção faria com que magicamente um Software saísse pronto e funcionando, no prazo, no custo e com muita qualidade. A partir desse conceito conheci a Engenharia de Software, que explicava os processos dessa linha de produção e durante algumas fases desse processo, eu conheci vários documentos, os maiores, melhores e mais bonitos que você possa imaginar.
Fiquei encantado com as mais variadas formas e tamanhos de documentos e já sentia o prazer de ter que fazê-los para resolver o problema do meu cliente.
Foi aí que me deparei com a Fábrica rival, que ficava bem na frente da antiga. Ela dizia que nada daquilo que a outra fazia era legal, que era muita burocracia, que os processos eram arcaicos e que se você seguisse a mais moderna linha de produção inventada por eles (que era meio que SUbway, onde você monta seu sanduíche) tudo daria certo e o Software seria entregue no prazo (que agora eram mais curtos e divididos em etapas).
Acontece que anos depois percebi que o grande problema de ambas as fábricas é que “todas” (a maioria pra ser mais exato) as atuais linhas de montagens, sofriam por conta de 2 fatores fundamentais:
1 - Elas haviam esquecido sua natureza e vendido seus princípios (quem manda mesmo é a $$);
2 - Elas dependem exclusivamente de “Pessoas alinhadas” (pensamentos, atitudes, objetivos e metas) para que dêm certo;
Quando cheguei a conclusão 2, percebi que a segunda “fábrica” (psiii, fala baixo, eles odeiam esse nome) estava mais próximo da realidade da maioria dos projetos os quais pude observar e que em sua natureza, ou seja, seu manifesto, estava tudo o que me era necessário para fazer qualquer projeto de Software dar certo. Claro, as novidades do mercado, como sempre, jamais deixaram de ser vendidas como a nova “bala de prata”, mesmo que disfarçada.
No final das contas, os princípios que me norteiam hoje são esses: http://www.manifestoagil.com.br/
Lhe contei essa historinha, pra lhe explicar o porque de minha opinião. Então lá vai.
Você precisa escrever documento pra que? É importante responder a essa pergunta, pois se você não souber essa resposta logo de primeira, gastará uma energia tremenda para algo que talvez não precise de documento.
Pra quem? Isso também é fundamental, pois se não houver QUEM leia o documento e ele não for obrigatório (já explico isso), novamente você desperdiçará energia a toa. E aqui mais uma pequena experiência. Em 100% dos casos onde escrevi ou consumi um documento, ele acabou sendo inútil e caro.
Inútil, porque uma verdade ABSOLUTA sobre Software é que ele muda. Muitas vezes ele muda 2 ou 3 vezes no mesmo dia e muitas vezes eu pegava um documento 10 horas da manhã e quando eram 6 da tarde ele já não prestava mais pra nada. E aí entra o outro fator, é caro, pois alguém tinha que ir lá pra atualizar esse documento. Os outros artefatos, que iam para as mãos do cliente, quando chegavam para que o mesmo assinasse como homologado, já estavam defasados e detalhe, viravam arquivo morto, ou seja, nunca mais eram remexidos.
Agora mesmo enquanto escrevo esse Post, tenho aqui num armário atrás de mim, pelo menos uns 20 Kg de papel que um dia foram escritos para servirem de base pra desenvolvimento e pra homologação de clientes. Todos, TODOS são inúteis e podem ser mandados para o lixo.
Então só pra concluir, se você tiver bem evidente em mente que realmente precisa de um documento e qual o objetivo deste, faça o seguinte, crie seu próprio layout. Não siga receita de bolo, layout da empresa X ou Y, pois esses layouts serviram bem pra eles, mas podem não servir pra você. Hoje eu uso meu próprio Layout de documentação e ele tem me servido muito bem, ele é da seguinte forma: Eu pego um rascunho da impressora, uma caneta Bic e desenho em cima do rascunho a ideia base. Como todo documento, o produto final fica BEM DIFERENTE e depois de me servir de guia, ele vai pro lixo.
Claro, aqui na minha equipe tem o pessoal da documentação, APF, etc. e todas essas coisas mais, pois a documentação é OBRIGATÓRIA (lembra que fiquei devendo explicação lá em cima?). Pois é, o cliente Obriga em contrato que criemos artefatos de todos os Projetos, mas quando rola alguma dúvida de como o Software funciona, eles chamam o líder técnico ou o analista de negócios para explicar, o que me mostra que não lêm o documento e quando o fazem percebem que o Software já não é mais aquilo que está escrito lá.
Agora só um adendo nessa história toda. Isso foi a MINHA observação em 12 anos de Desenvolvimento de Software, tendo trabalhado como Programador (PHP e Java) e Analista de Requisitos/Negócio. Pode ter algum colega aqui com a experiência bem diferente da minha, porém posso apostar que se isso aconteceu, ele trabalhou em uma equipe alinhada (prestador de serviço e cliente) e com princípios bem ligados à fábrica original.
Enfim, espero mesmo ter sido útil com minha opinião. Ela é bem direta: “Use a sua energia pra fazer perfeito aquilo que você REALMENTE vai usar. E se for um documento para a sua realidade (que não é a mesma que a minha, não é a mesma que da IBM ou da Oracle), construa o seu próprio Layout com aquilo que vai ser importante pra você”. Sem mais.
Abraços e sucesso na jornada. 
Realmente um assunto polêmico. Se for trabalho de faculdade ok, o que exatamente na prática está lidando?
Jah dizia o sabio, qualquer um pode escrever codigo para que o computador entenda, mas soh os bons escreveram para que as pessoas entendam e isso vale para a engenharia de software, eu compartilho dessa ideia.
Eu compartilho da ideia de algo ágil, independentemente de haver alguma clausula contratual ou um gerente achando que o funcionário está se apoderando de ativos da empresa (poder intelectual) por conta de “falta de documentação”.
Bela explanação.
[]'s
Muito bem lembrado cara…
Aí está algo com o qual nunca lidei, mas já ví casos bem reais próximos a mim. Onde ví tal caso, foi mais um desgaste do cliente com a fornecedora na época que fez com que a exigência subisse alguns níveis. No final das contas o prestador de serviço foi mandado embora e outro que foi chamado no lugar que ficou com a tarefa ingrata de ter que decifrar o Sistema do antigo através dos códigos.
Os documentos acabaram não servindo pra nada, mas e se tivessem sido bem escritos?
No final das contas acho que é nesse “Escrever bem escrito” que mora a raiz do problema.
Abs []
Desculpem fugir do assunto, se eu abrir um projeto a primeira coisa que eu olharia seria a disposição das classes e pacotes bem como a nomenclatura, ou seja, a adoção de algum padrão, etc.
Segundo, aquele layout apontado pelo @adriano_si e se não for um artefato com a fonte 7, um diagrama de classe e/ou sequência o que acabaria caindo no mesmo problema de desatualização em comparação com o programa.
[]'s
Procura por UML.
Se você esta falando sobre o documento receita que serve pra dizer quanto vai custar o bolo, procure sobre Especificação de Casos de uso.
Quanto mais obvio o documento for melhor, ex:
Fluxo Alternativo C3
-Autor Clica no Botão Voltar
-Sistema retorna para a tela anterior
Fluxo Alternativo C4
-Autor Clica no Botão Sair
- Sistema sai da funcionalidade.
Fluxo alternativo C5
- Autor Clica no Botão Salvar
- Sistema Salva as informações. (aqui pode ser pior, pode ter outro fluxo alternativo dizendo que sistema valida as informações e apresenta erros ou então salva)
Tipo essas coisas que são obviamente obvias, conforme for criando mais telas, é só dar ctrl+c no documento, depois alterar o nome dos campos, o nome da funcionalidade, e voya-la 20 telas de cadastro, 20 paginas cada documento, você já tem uma documentação de 400 paginas para 20 telas. claro um monte de clone, se colocar uma capa bem bonita e fica bonito na estante.
(ai o cara vai la altera uma validação em um dos casos de uso, pega as 20 paginas, bota la em cima, Atualização 1.1, Data Atual e entrega pro desenvolvedor).
Se for um desenvolvedor novo no projeto, pra criar essa validação ele vai ler as 20 paginas do documento, chorar um pouco, depois ler o documento anterior, e voya-la ele descobre onde ele tem que alterar, vai la e altera… boa, tempo da alteração + testes de outra equipe que também vai ler os documentos, testar e fazer os casos de teste pra ver se nada foi quebrado: 1 semana.
Eu não estou brincando, isso acontece…alguém mais já deve ter visto isso.
Na verdade, não é bem assim como você está falando. Hoje em dia, se usa, antes de iniciar o documento, um histórico de atualizações, onde você pode verificar quais as alterações realizadas no documento, sem precisar ter que ler o documento todo novamente. Depende do cuidado do analista de requisitos.
Concordo, que devemos buscar meios de melhorar cada vez mais as documentações, acredito que elas podem ficar cada vez mais simples. Se você for pensar numa pessoa que não conhece nada do sistema e que precisa de uma orientação de como funciona os objetos dentro do sistema, creio que a documentação ainda continua sendo o melhor método para conhecimento.
Tópico muito interessante. Por acaso estou trabalhando como autonomo e fico pensando em documentar o software.
A única coisa que estou fazendo é a modelagem/relacionamento de classes.
Eu não sei voces mas eu acho que a documentação ajuda e MUITO. No meu caso trabalhei com auxiliar de testes de software por alguns anos e houve uma época em que a empresa trocou o bando de dados para o ORACLE. Tivemos que realizar testes (no caso fiz testes funcionais e metade no banco de dados) em todos os módulos do ERP da empresa e,meu amigo, senão fosse a documentação existente eu estava fudido pois muitas vezes não tinha como utilizar um recurso (no caso uma pessoa da área) como fonte de informação para aprender o processo e assim realizar um teste sólido e conciso.Fora que muito das telas não tinha documentação e eu tive que aprender ou na intuição ou na raça mesmo e pesquisando por ai rsrsrs.
Caso alguem tenha interesse em saber era uma empresa grande de logistica e transportes.