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.
[quote=Thiago de Paula Beserra]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. [/quote]
“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.
[quote=Thiago de Paula Beserra]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.
[/quote]
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…