Como criar um bom manual sobre aplicativos ? No meu caso falo de Shell Script.

AprendiNoLinux
(usa Ubuntu)

Enviado em 23/04/2012 - 14:09h

Participei recentemente de um tópico aqui no VOL que abordava a engenharia de Software. Para saber mais: http://www.vivaolinux.com.br/topico/Engenharia-de-Software/Especificacao-de-Requisitos/


Documentar scripts e aplicativos é um pé no saco. Andei pesquisando sobre alguns software para gerar documentação de Shell Script e não encontrei nada que fosse útil. Alguém já viu algum ? Tem aplicativos para sugerir ?

Também estou interessado em materiais que orientem a construção de um bom manual de software. Tem tanta coisa na NET mas muito teórico. Quero algo prático para usar no dia a dia mesmo.

Palpiteiros de plantão... mandem um sinal de fumaça ou qualquer dica que vou atrás.

AprendiNoLinux
(usa Ubuntu)

Enviado em 23/04/2012 - 14:32h

Estou tentando algo que seja similar ao Doxygen para documentar os Scripts Shells porque estão ficando grandes: http://code.google.com/p/eater-thief/wiki/Doxygen

Mas não achei nada para SH.

AprendiNoLinux
(usa Ubuntu)

Enviado em 23/04/2012 - 21:13h

Desistindo do Doxygem porque só documenta C, embora sh tenha alguma similaridade a nível de escrita.

AprendiNoLinux
(usa Ubuntu)

Enviado em 23/04/2012 - 21:31h

Se você é um desenvolvedor que diz ao usuário que seu sistema é tão simples que não precisa de manual, seu sistema ou é mesmo muito interativo ou você está fadado ao fracasso.

Consultar o manual de sistemas não é uma atividade apenas do usuário e sim dos desenvolvedores e analistas. Um bom manual até onde pesquisei na NET deve conter tanto a parte técnica destinada a experts, consultores, analistas e membros do suporte.

Já o guia do manual destinado a usuários finais não deve conter questões técnicas.

Mesmo fazendo várias pesquisas sobre alguns exemplos de manuais de sistemas, ainda não tenho claro uma sequência lógica para cria-lo.

Via de regra os manuais começam pela instalação, passam pelas configurações. Depois a maioria se perde no quesito como usar o software. A maioria corre das questões técnicas. É justamente neste ponto que acho morar o maior erro dos criadores de sistemas. Falo por eu mesmo. A mais ou menos 8 meses criei um sistema com praticamente zero de documentação técnica. Apenas lendo o que coloquei nos scripts não me ajudou muito. Alterar um sistema que tem mais de 200 funções espalhadas em vários arquivos não é trivial. Desconfio que todo tempo que ganhei por não te-lo feito na época do desenvolvimento estou perdendo em dobro agora. Triste constatação e que não quero cometer este erro novamente.


A maioria vai dizer que usuário nenhum consulta manual. Grande engano. Nestes 8 meses de via da versão 1.0 tive que intervir mais de 50 vezes. O sistema é ruim ? kkk Eu acho que não. Gerar esta dependência com o usuário e a equipe de suporte não é o que espero. Ao contrário do que andei lendo em sites de suporte, tem muito desenvolvedor que gosta de ver o usuário dependente. Na minha visão isto é um erro. Quando mais ele não te encher o saco, mas poderá dar feedback para melhorias. Mais eu posso trabalhar em paz. Sou programador e não da equipe de suporte aos usuários.

Não estou falando em fazer um manual estilo “how-to”, e sim algo para aprender e melhorar com o tempo. Estes dias tenho [riscado]perdido[/riscado] investido grande parte do meu tempo em documentação do sistema. Percebi que até eu mesmo não lembro porque algum tipo de função foi criada. O que pensava quando a fiz. Está sendo um grande aprendizado para mim. Estou pensando em criar um manual que a prioridade seja a usabilidade do próprio manual. Acho que o melhor caminho está em criar páginas de html. Embora em Shell seja ruim para demonstrar on-line a utilização integrada. Se o manual inteiro fosse em shell seria melhor para mim kkkk.

Apenas um desabafo para ver se alguém pode dar algumas ideias ou um norte para este scripteiro aprendiz. ;)

AprendiNoLinux
(usa Ubuntu)

Enviado em 23/04/2012 - 23:22h

Um dos melhores que encontrei até o momento como guia prático foi este: http://www.selursocial.org.br/manuais.html

Peca na parte técnica apenas. Realmente é enfadonho criar manuais técnicos kkkk.

"Prestenção" não é MANUAL bosta é MANOEL BOSTA.

parrera
(usa Debian)

Enviado em 24/04/2012 - 00:08h

são scripts de que?

estão ficando grandes?

este site é um bom inicio para trabalhar com o shell script:
http://www.afms.com.br/shell/?page=2#docu


o que você quer dizer com manual de software?

parrera
(usa Debian)

Enviado em 24/04/2012 - 00:26h

ae...acho que entendi um pouco o que vc quer dizer com o manual.

acho que fica a seu criterio.
um manual de um sistema inteiro me parece complexo.
mas uma documentação do software mais simples me parece mais tangível.
por partes e caso necessário faria:

* acho que deveria conter como compilar (comandos) tal sistema e suas dependências necessárias ou então como proceder para instalar diante do Setup (se vc disponibilizou) primordial e essencial;

* fazer as configurações iniciais se necessário para o software funcionar seria outro ponto importante;

* esclarecer os comandos básicos ou as funções dos botões da interface, viria em 3º.

* dar exemplos de caso uso das funcionalidades seria a última coisa que iria me preocupar, só se o sistema fosse muito grande ou por razões organizacionais.

esses pontos que citei são mais do ponto de vista do usuário do software.

Agora, sobre documentação do software para um desenvolvedor por exemplo, daria mais enfoque do documento de especificação dos requisitos, diagramas de classe, sequencia, arquitetura geral, casos de teste (unitários e de integração), como compilar e configurar.


Não sei se estou contribuindo com algo...

AprendiNoLinux
(usa Ubuntu)

Enviado em 24/04/2012 - 11:06h

O maior problema são as bibliotecas de uso geral.
Sim, não param de crescer kkk e bugar.

O link valeu porque esta parte ainda não sei como fazer.



Preciso com urgência aprender a criar mans pages.

AprendiNoLinux
(usa Ubuntu)

Enviado em 24/04/2012 - 11:14h

Claro que está contribuindo. O trivial para alguns não é para outros. O roteiro que você descreveu acima já estou em parte organizando. Só não sei ainda qual a melhor forma para compor os manuais.
Tinha iniciado com arquivos de texto dentro de um diretório abaixo das aplicações com a extensão .doc, mas estou revendo. Para usa-los dentro do SH vou precisar ver o formato interno dos arquivos. Não basta escrever o texto estruturado. Precisa ser possível fazer pesquisas ao longo do texto. Daí a necessidade de ver como funcionam as mans pages e talvez seja o caminho para montar toda parte técnica. Deixarei o lado do usuário em html porque fica mais fácil de compor, alterar e adicionar conteúdo visual com fotos e tals.

Percebi que deixar de lado a especificações das funções foi um grande erro que cometi. Separar as dicas que tinha colocado dentro das funções foi outro erro. Melhor documentar mais a função do que deixar em arquivos separados. Na época pareceu que seria bom. Na prática foi um grande erro. Quando precisei mudar o nome de várias funções para acrescentar alias e name space quebrei todos os documentos das funções porque estavam separadas do código kkkk.

Mas aprender com os erros as vezes é melhor do que não vivencia-los. Fico mais preparado para enfrentar novos desafios e esperto para entender que é preciso investir mais tempo em documentações do que as vezes programando.

Sugestões sempre bem vindas.

###############################################################################

## APLICAÇÃO: gserv - Manual geral.

###############################################################################

## ../../../gserv/docs/*.*

###############################################################################

## Histórico de alterações.: gserv.changelog.doc

## Configurações do gserv..: gserv.config.doc

## Notícias sobre o gserv..: gserv.news.doc

## Manual do gserv.........: gserv.manual.doc (ESTE DOCUMENTO)

## Help do gserv...........: gserv.help.doc

## Manual das bibliotecas..: gserv.libs.doc

###############################################################################

##

###############################################################################

############################### SUMÁRIO #######################################

###############################################################################

##----------------------------------------------------------------------------#

## docs		-	Tudo que você precisa saber sobre o desenvolvimento ou dicas

##				de como utilizar estarão neste diretório.

##				Nenhum arquivo contido neste diretório tem poder de execução.

##----------------------------------------------------------------------------#

## libs		-	Bibliotecas especificas para o app. É importante documentar bem

##				cada biblioteca porque geralmente ganhará muito tempo no futuro.

##				Se tiver a chance de desenvolver uma lib que seja independente

##				da aplicação atual, escolha faze-lo. Só faça libs para o

##				aplicativo se for realmente necessário.

##				Nenhum arquivo dentro deste diretório poderá ter poder de

##				execução. Só podem ser acessados via aplicativo gserv.

##----------------------------------------------------------------------------#

## progs	-	Local onde você encontra todos os scripts que não sejam de

##				configurações, libs ou específicos. Considere como sendo o

##				diretório oficial do aplicativo. Arquivos devem ter poder de

##				execução.

##----------------------------------------------------------------------------#

## configs	-	Só para arquivos de inclusão e não devem ter poder de execução.

##----------------------------------------------------------------------------#

## servicos	-	Pasta de atividade exclusiva deste app. Exemplo.

##............................................................................#

##				registros.de.servico -	Pasta que recebe o cadastro de futuros

##										ou serviços em atividade.

##										Futuramente será usada para automatizar

##										a geração de algum novo serviço.

##............................................................................#

##				InsereContas >>>>>> Pasta de um determinado serviço.

##									Este é apenas um dis serviços em atividade.

##									Futuramente a maioria do que roda em cron

##									será transformado em serviços e tarefas.

##............................................................................#

##					exec >>>>>>	Pasta onde ficam os scripts que serão executados

##								pelas rotinas do gserv.

##								Precisam ter poder de execução.

##............................................................................#

##					includes >>	Arquivos que serão incluídos pelos scripts

##								que executam as tarefas ou pelo gserv.

##								Geralmente tratam de variáveis GLOBAIS.

##								Qualquer arquivo nesta pasta não pode ter

##								poder de execução.

##............................................................................#

##					tarefas	>>> Scripts que efetivamente irá usar o aplicativo

##								gserv. Considerar como sendo os disparadores.

##								Cada script nesta pasta tem que ser diferente.

##								Cada um tem a sua própria configuração de uso.

##								Aqui você cria cada tarefa desejada.

##								O nome do arquivo representa a tarefa do serviço

##								Qualquer arquivo neste diretório precisa ter

##								direito de execução.

##----------------------------------------------------------------------------#

###############################################################################

 

Miqueloti
(usa Lubuntu)

Enviado em 24/04/2012 - 13:44h

Realmente é frustrante quando você precisa dar um upgrade em seu código e você não sabe mais como fez aquilo rsrsrs...

Eu normalmente faço na munheca o manual para users, e para mim apenas deixo os códigos muito bem comentados para saber o que cada função, loop complexo, ou outra estrutura que exija mais lógica para entendimento não ser esquecida com o tempo.