Arquivo Discussoes de Programacao e Tecnologia Pessoal, boa tarde
Estou com uma demanda para documentar uma aplicação que fiz no trabalho. Nunca documentei uma aplicação profissionalmente. Queria saber com os amigos do GUJ se existe algum modelo a seguir, padrões etc. Existe mais de um modelo?
Agradeço pela ajuda. 
Depende muito do que seu chefe está pedindo.
Um padrão que pode ser usado é o Javadoc.
Pessoal, boa tardeEstou com uma demanda para documentar uma aplicação que fiz no trabalho. Nunca documentei uma aplicação profissionalmente. Queria saber com os amigos do GUJ se existe algum modelo a seguir, padrões etc. Existe mais de um modelo?
Agradeço pela ajuda.
“Documentar a aplicação” é muito genérico. Documenter o quê ?
Uma forma padrão é montar um Manual do Usuário. isso documento como se usa e o que se espera que aconteça. A navegação, as features ,etc… Não se documenta como acontece.
O javadoc que já falaram é para documentar o código e API. é para ser usado por outros programadores.
Se precisar documentar a arquitetura então ha outras visões que têm que ser adotadas. E assim vai.
Não existe um documento que documente tudo sobre a aplicação. Vc tem que definir documentos que explicam uma faceta ( uma visão, uma prespectiva) da aplicação. E por isso uma aplicação têm normalmente muitos documentos que a documentam.
Mas cuidado em não documentar visões demais. É bom que elas não se sobreponham ou estará documentando a mesma coisa várias vezes.
Como consideração final : documentar significa que a pessoa que ler vai entender. Isto significa que vc tem que escrever com palavras. Bonecos e gráficos não são documentação. São auxiliares do que é escrito. UML por exemplo, é util, mas apenas acompanhada de uma explicação em texto. Não existe um diagrama à prova de bala, portanto a única coisa à prova de bala é o texto. É ele que tem que ser claro, não ambíguo, com cada palavra sendo usada com consciência.
Isso, na verdade é um manual para o usuário. Exemplo. É uma aplicação X que tem por objetivo suprir as necessidades y, z etc.
Falar sobre os campos, mensagens do sistema, log de processamento etc.
Estava lendo o manual do DropBox esses dias e achei bem montado, bem explicado. O que acham se eu fizer parecido? A aplicação que desenvolvi não é de grande porte não, é uma tela só com processamento voltado para um servidor de E-mail.
segue em anexo pra quem ainda não leu ou viu.
Estava lendo o manual do DropBox esses dias e achei bem montado, bem explicado. O que acham se eu fizer parecido? A aplicação que desenvolvi não é de grande porte não, é uma tela só com processamento voltado para um servidor de E-mail.segue em anexo pra quem ainda não leu ou viu.
Vc precisa uma pouco mais que isso. Aquilo não é uma manual é um Quick Start ( menos que um manual, só para os primeiros passos).
Mas os estilo é aquele. Bem leve, com imagens, screen shots , bem explicados no texto, com referencia. Usar um glossário é bom ( o que significa “mensagem” ?) e depois usar sempre as mesmas palavras com o signficado do glossário. O sistema é simples de entender quando menos ambiguo forem as palavras e quando menos conceitos forem necessários.
Use sempre a mesma linguagem. Se começa usando "O usuário … " não troque depois para "Você … ". Não diga “O usuário clica no botão” e sim “O usuário faz clique no botão” , é preciso ter um cuidado redobrado com a linguagem que usa e com a própria língua PT.
Depois , se possivel , faça um teste com um ou dois usuários para que eles leiam e lhe reportem duvidas e feedback. Esta é a melhor ferramenta possível.
Entendi
No caso mensagem seria um alerta caso a conexão com a internet não estivesse disponível, ou caso o usuário informasse um diretório inválido para armazenar um anexo que será salvo fisicamente.
Desculpa a ignorância, o que seria FeedBack?
Retorno ( tradução literal). Em electronica é “retroalimentação”
Retorno no sentido de vc mostrar para o usuário ele sentir que realmente o manual o ajuda e explica o que ele precisa. O manual não pode deixar o cara na mão ( :lol: :lol: ).
É bom fazer com usuários que nunca usaram o sistema, e com usuarios que já usaram. Os primeiros vão testar se o manual realmente explica o básico necessário para entender o sistema, e os outros se eles explica todos as features que o sistema tem.
Retroalimentação no sentido que vc vai usar os comentários deles para fazer um manual melhor. Se vc poder usar essa comunicação, é excelente, porque vc fará uma manual conforme o usuário precisa. Sem isso, vc se limita a explicar as telas, os botões, como realizar as tarefas, etc… pode não ser suficiente.
Muito Obrigado pelas dicas. Fico bem explicado. Valeuu…