Formas práticas de planejamento e documentação de um sistema

rafadelnero · Março 7, 2013, 5:59pm

Eu estava pensando se é realmente necessário usar diversos tipos de diagramas pra planejar um sistema Web ou de qualquer tipo, será mesmo? Acham que levantamento dos requisitos iniciais, caso de uso com cenário principal e alternativo e diagrama de classes está bom pra poder implementar um sistema? Com o diagrama de classes podemos gerar o modelo do banco de dados automaticamente eliminando assim a modelagem do banco.

Ao meu ver já é o suficiente, possibilitando até desenvolver um sistema grande, concordam?

rogeriopaguilar · Março 7, 2013, 6:25pm

eu acho que depende… se for você mesmo que vai desenvolver acho que não tem problemas… Agora imagina se for algum lugar que ainda utiliza divisão de trabalho onde quem programa não se envolve com o levantamento (sim, isso ainda existe) e recebe documentação para desenvolver… ou então uma equipe muito grande espalhada remotamente… neste caso eu acho que quanto mais detalhes você conseguir passar para quem vai implementar é melhor. Agora se for você que vai desenvolver um módulo desde o começo, fazendo desde o levantamento até a implantação, então acredito que o que você disse pode ser verdadeiro, até porque como foi você mesmo que fez o levantamento de dados muita coisa estará na sua cabeça, enquanto que no outro cenário pra alguém conseguir saber o que está na sua cabeça teria que ler isso em algum lugar

Valeio_Bezerra · Março 7, 2013, 6:30pm

Cara assim, se você tiver tempo quanto mais documentação melhor, o problema é a falta dele. Uma modelagem de dados(tabelas, campos e ligações) já é o suficiente para entender, ao meu ver, mas digo como diz meu avô: “É melhor sobrar do que faltar”.

sergiotaborda · Março 7, 2013, 6:45pm

[quote=rafadelnero]Eu estava pensando se é realmente necessário usar diversos tipos de diagramas pra planejar um sistema Web ou de qualquer tipo, será mesmo? Acham que levantamento dos requisitos iniciais, caso de uso com cenário principal e alternativo e diagrama de classes está bom pra poder implementar um sistema? Com o diagrama de classes podemos gerar o modelo do banco de dados automaticamente eliminando assim a modelagem do banco.

Ao meu ver já é o suficiente, possibilitando até desenvolver um sistema grande, concordam?[/quote]

Quando vc pensa o que tomar de cafe da manhã , ou qual o caminho para o shopping ou qual a roupa que vai usar, vc faz um boneco num papel ?
Não.

Porquê ?

Porque vc não precisa comunicar com mais ninguém.

Pensar é a coisa mais rápida que existe. Vc pensa e logo atua. Pronto.

Mas quando vc quer explicar sua ideia, ou explicar pq sua roupa combina, ou explicar como a outra pessoa pode chegar no shopping, é legal uma ajuda visual.
Ai vc desenha num pedaço de papel um mapa, ou um diaram de alguma forma que ajude a visualizar o que vc está pensando.
Este tipo de artefacto é útil para a comunicação, mas não é uma documentação.

Uma documentação exisge um nivel de abstração e linguagem que seja util a várias pessoas. Por exemplo, para ir para o shoping vc precisa de um ponto de partida, cada pessoa terá o seu. Por isso precisamos do google maps , :lol:

Então entenda que “documentação para planejamento” é equivalente a criar (não usar, criar) o google maps para ir num lugar que vc já chegou. é uma antítese.
Planejamento pode ser feito na sua cabeça ou num pedaço de papel que é apenas um auxiliar visual para a comunicação e para a sua memoria também. Mas é apenas isso. Não é uma documentação.

Se vc está numa equipe ou vc está planejando algo que vai decrrer um longp periodo de tempo ( um dia pode ser longo se sua memoria for ruim) é bom vc usar algum atefato “persistente”. Uma lousa, um papel, sei lá… isso ajuda a pensar.

DOcumentação é apenas uma forma de comunicação. A mais persistente de todas e a mais abranjente que tem que lidar com diversos perfis de pessoas. Por isso que nos livros fala assim "este livro se destina a … " Documentação tem uma audiência especifica. Se vc está fora dessa audiencia, não vai fazer sentido. Por isso documentar é muitos mais complexo e tecnico do que simplesmente escreve uns bonecos.

rafadelnero · Março 7, 2013, 6:47pm

Concordo que em grandes equipes a documentação deva ser mais detalhada. Ou até não seria preciso com as documentações que eu citei se houver diversos subgrupos, explicando os detalhes maiores para cada líder dos subgrupos, ele irá delegar para os demais tendo um controle maior no andamento das tarefas.

rafadelnero · Março 7, 2013, 6:53pm

[quote=sergiotaborda][quote=rafadelnero]Eu estava pensando se é realmente necessário usar diversos tipos de diagramas pra planejar um sistema Web ou de qualquer tipo, será mesmo? Acham que levantamento dos requisitos iniciais, caso de uso com cenário principal e alternativo e diagrama de classes está bom pra poder implementar um sistema? Com o diagrama de classes podemos gerar o modelo do banco de dados automaticamente eliminando assim a modelagem do banco.

Ao meu ver já é o suficiente, possibilitando até desenvolver um sistema grande, concordam?[/quote]

Quando vc pensa o que tomar de cafe da manhã , ou qual o caminho para o shopping ou qual a roupa que vai usar, vc faz um boneco num papel ?
Não.

Porquê ?

Porque vc não precisa comunicar com mais ninguém.

Pensar é a coisa mais rápida que existe. Vc pensa e logo atua. Pronto.

Mas quando vc quer explicar sua ideia, ou explicar pq sua roupa combina, ou explicar como a outra pessoa pode chegar no shopping, é legal uma ajuda visual.
Ai vc desenha num pedaço de papel um mapa, ou um diaram de alguma forma que ajude a visualizar o que vc está pensando.
Este tipo de artefacto é útil para a comunicação, mas não é uma documentação.

Uma documentação exisge um nivel de abstração e linguagem que seja util a várias pessoas. Por exemplo, para ir para o shoping vc precisa de um ponto de partida, cada pessoa terá o seu. Por isso precisamos do google maps , :lol:

Então entenda que “documentação para planejamento” é equivalente a criar (não usar, criar) o google maps para ir num lugar que vc já chegou. é uma antítese.
Planejamento pode ser feito na sua cabeça ou num pedaço de papel que é apenas um auxiliar visual para a comunicação e para a sua memoria também. Mas é apenas isso. Não é uma documentação.

Se vc está numa equipe ou vc está planejando algo que vai decrrer um longp periodo de tempo ( um dia pode ser longo se sua memoria for ruim) é bom vc usar algum atefato “persistente”. Uma lousa, um papel, sei lá… isso ajuda a pensar.

DOcumentação é apenas uma forma de comunicação. A mais persistente de todas e a mais abranjente que tem que lidar com diversos perfis de pessoas. Por isso que nos livros fala assim "este livro se destina a … " Documentação tem uma audiência especifica. Se vc está fora dessa audiencia, não vai fazer sentido. Por isso documentar é muitos mais complexo e tecnico do que simplesmente escreve uns bonecos.[/quote]

Você acha que desenvolver o sistema sem documentação e sem planejamento é muito passível a mudanças e erros?

raf4ever · Março 7, 2013, 7:03pm

Nesse caso o melhor mesmo é fazer na medida certa.

Precisou de documentação?Documenta.Mas não documenta apenas pra encher linguiça,é um tremendo desperdicio de tempo.

sergiotaborda · Março 7, 2013, 8:44pm

[quote=rafadelnero][quote=sergiotaborda]
DOcumentação é apenas uma forma de comunicação. A mais persistente de todas e a mais abranjente que tem que lidar com diversos perfis de pessoas. Por isso que nos livros fala assim "este livro se destina a … " Documentação tem uma audiência especifica. Se vc está fora dessa audiencia, não vai fazer sentido. Por isso documentar é muitos mais complexo e tecnico do que simplesmente escreve uns bonecos.[/quote]

Você acha que desenvolver o sistema sem documentação e sem planejamento é muito passível a mudanças e erros?[/quote]

Desenvolver sem planejamento é suicidio. E aliás bem dificil que não haja nenhum planejamento.
Sem documentação é tranquilo. No desenvolvimento vc ainda não sabe bem o que vai ser. Documentar é fútil.
Depois que vc decidiu , ai sim, documentar é útil. Porque não vai mudar mais.

Vcs estão pensando que “maior equipe => mais detalhe na documentação” . Isto é nonsense. significa que quando maior a equpe mais detalhes eu preciso explicar. Obivamente não é isso. Os mesmos detalhes têm que ser explicados , não importa para quantas pessoas. Um livro é um livro, não importa quantos o vão ler. O que o autor pretende dizer ele vai dizer a 1 ou a 1 milhão. Não importa. Aliás , essa é a graça de documentar.

Por outro lado, estão confundindo documentação com comunicação. O que eu preciso que os programadores saibam eu lhes digo. Isso é comunicação. não preciso escrever um word de 200 páginas. A palavra falada é mais rápida.
Então , comunicação não exige documentação, mas documentação é uma forma de comunicação. Mas não é a única e não é a mais eficiente durante um período de mudanças que caracteriza o desenvolvimento.

E se alguém está pensando, especificar também não se faz com diagramas. UML, por exemplo, é uma Linguagem. linguagens servem para comunicar. Se a comunicação será documentada ou não, é outra conversa.

Tlv as pessoas estejam pensando que "maior equipe = equipe mais distribuida => mais comunicação = mais documentação"
A equipe se distribuida não tem relação com ser grande ou pequena. O tamanho da equipe e a localização da equipe são variáveis ortogonais.
Uma equipe maior ou mais distribuida não precisa de mais comunicação. Precisa de comunicação mais eficiente. Documentar não é a forma mais eficiente. Pair programming, por exemplo, é mais eficiente.
Mais comunicação não implica em mais documentação.

Finalmente, é preciso não confundir documentação com especificação. Especificação é feito antes, documentação é feito depois. O manual do usuário é uma documentação, a lista de requisitos é uma especificação. Lá porque ambas se escrevem (tradicionalmente) no word ( são “documentos do word”) não os torna documentação. Esta distinção é onde está o cerne da resposta. Planejamento precisa de especificação, não de documentação. A especificação é mutável, a documentação é imutável ( porque ela é gerada após o fato).

rafadelnero · Março 8, 2013, 2:40am

[quote=sergiotaborda][quote=rafadelnero][quote=sergiotaborda]
DOcumentação é apenas uma forma de comunicação. A mais persistente de todas e a mais abranjente que tem que lidar com diversos perfis de pessoas. Por isso que nos livros fala assim "este livro se destina a … " Documentação tem uma audiência especifica. Se vc está fora dessa audiencia, não vai fazer sentido. Por isso documentar é muitos mais complexo e tecnico do que simplesmente escreve uns bonecos.[/quote]

Você acha que desenvolver o sistema sem documentação e sem planejamento é muito passível a mudanças e erros?[/quote]

Desenvolver sem planejamento é suicidio. E aliás bem dificil que não haja nenhum planejamento.
Sem documentação é tranquilo. No desenvolvimento vc ainda não sabe bem o que vai ser. Documentar é fútil.
Depois que vc decidiu , ai sim, documentar é útil. Porque não vai mudar mais.

Vcs estão pensando que “maior equipe => mais detalhe na documentação” . Isto é nonsense. significa que quando maior a equpe mais detalhes eu preciso explicar. Obivamente não é isso. Os mesmos detalhes têm que ser explicados , não importa para quantas pessoas. Um livro é um livro, não importa quantos o vão ler. O que o autor pretende dizer ele vai dizer a 1 ou a 1 milhão. Não importa. Aliás , essa é a graça de documentar.

Por outro lado, estão confundindo documentação com comunicação. O que eu preciso que os programadores saibam eu lhes digo. Isso é comunicação. não preciso escrever um word de 200 páginas. A palavra falada é mais rápida.
Então , comunicação não exige documentação, mas documentação é uma forma de comunicação. Mas não é a única e não é a mais eficiente durante um período de mudanças que caracteriza o desenvolvimento.

E se alguém está pensando, especificar também não se faz com diagramas. UML, por exemplo, é uma Linguagem. linguagens servem para comunicar. Se a comunicação será documentada ou não, é outra conversa.

Tlv as pessoas estejam pensando que "maior equipe = equipe mais distribuida => mais comunicação = mais documentação"
A equipe se distribuida não tem relação com ser grande ou pequena. O tamanho da equipe e a localização da equipe são variáveis ortogonais.
Uma equipe maior ou mais distribuida não precisa de mais comunicação. Precisa de comunicação mais eficiente. Documentar não é a forma mais eficiente. Pair programming, por exemplo, é mais eficiente.
Mais comunicação não implica em mais documentação.

Finalmente, é preciso não confundir documentação com especificação. Especificação é feito antes, documentação é feito depois. O manual do usuário é uma documentação, a lista de requisitos é uma especificação. Lá porque ambas se escrevem (tradicionalmente) no word ( são “documentos do word”) não os torna documentação. Esta distinção é onde está o cerne da resposta. Planejamento precisa de especificação, não de documentação. A especificação é mutável, a documentação é imutável ( porque ela é gerada após o fato).
[/quote]

Você acha adequado planejar um sistema na cabeça? Se for um sistema relativamente grande diversos detalhes podem passar despercebidos. Talvez um diagrama de classes e levantamentos requisitos não ajudariam no processo?

javaflex · Março 8, 2013, 3:14am

[quote=rafadelnero]Eu estava pensando se é realmente necessário usar diversos tipos de diagramas pra planejar um sistema Web ou de qualquer tipo, será mesmo? Acham que levantamento dos requisitos iniciais, caso de uso com cenário principal e alternativo e diagrama de classes está bom pra poder implementar um sistema? Com o diagrama de classes podemos gerar o modelo do banco de dados automaticamente eliminando assim a modelagem do banco.

Ao meu ver já é o suficiente, possibilitando até desenvolver um sistema grande, concordam?[/quote]
Usa só o que for te ajudar no desenvolvimento e principalmente evolução, quando não ajuda vira só processo burocrático.

Valeio_Bezerra · Março 8, 2013, 11:30am

Documentar, você tem que documentar sim, por que você pode esquecer no que você pensou(Quase impossível de não acontecer) e a documentação vai te ajudar a visualizar melhor o conceito, por que depois que o programa pronto e vê que o conceito do sistema está errado é dose, isso acontece com ou sem documentação, mas com a documentação é mais fácil de ajustar e mais difícil de errar no conceito.

sergiotaborda · Março 8, 2013, 12:58pm

[quote=rafadelnero][quote=sergiotaborda]
Finalmente, é preciso não confundir documentação com especificação. Especificação é feito antes, documentação é feito depois. O manual do usuário é uma documentação, a lista de requisitos é uma especificação. Lá porque ambas se escrevem (tradicionalmente) no word ( são “documentos do word”) não os torna documentação. Esta distinção é onde está o cerne da resposta. Planejamento precisa de especificação, não de documentação. A especificação é mutável, a documentação é imutável ( porque ela é gerada após o fato).
[/quote]

Você acha adequado planejar um sistema na cabeça? Se for um sistema relativamente grande diversos detalhes podem passar despercebidos. Talvez um diagrama de classes e levantamentos requisitos não ajudariam no processo?[/quote]

Vc não está querendo entender o que estou dizendo. O MiddleHeaven tem mais de 1800 classes. Vc acha que eu decorei todas ? Obviamente não. Mas sei o que cada uma faz ? sim. Precisei de documentar isso tudo ? não. Por quê ?

É importante entender por quê! Porque eu não precisei de explicar essa classes a ninguém**.

Agora, se vc me perguntar : vc nunca fez um boneco de organização disso ? Fiz. E alguns estão no proprio projeto em jude/astar, mas isso é documentação ? Não. É apenas um boneco. É uma ajuda de memória. Ninguem entender o MH vendo esses diagrama UML.

Todo o planejamento é feito mentalmente. Não se engane do contrário. É por isso que é preciso ter alguem com a visão do todo “the big picture”) ou o projeto sia torto. Não importa como vc chama a pessoa que tem esta visão, mas ela tem que existir ou não ha software. Bonecos podem ajudar a pensar, podem ajudar a comunicar, mas não são documentação.

A palavra “documentação” existe um peso e um calibre de linguagem que vc não precisa e não pode usar no dia a dia. Seria demasiado burocrático. É esse o erro das fábricas de software. Não adianta o cara passar 2 meses fazendo um uml se o cara que vai ler não sabe ler UML, e mesmo que saiba , tem cosias que não vão está lá escritas.

Quando vc diz "Você acha adequado planejar um sistema na cabeça? " Parece que vc quer dizer "Você acha adequado memorizar um sistema na cabeça? ". Não é a mesma coisa. Planejar não é memorizar. É um processo. É dinâmico. O que vc precisa lembrar está no código, e o que não pode ficar no código vc deixa num papel, numa lousa, numa wiki, etc… mas essas cosias não são documentação.

Se a sua pergunta é “deve criar artefactos que me ajudem a memorizar o que eu decidi para o software?” A resposta é: sim. Se vc pergunta "esses artefactos são documentação do software? " a resposta é : não.

Entenda a diferença.

Mais detalhes vc pode encotrar neste livro, que explica o real valor da documentação e o real valor de auxiliares de memoria. Procure também pelo conceito de “agile architecture”

P.S. ** E exactamente porque não tem formas de explicar, que ninguem usa lol. É complicado documentar as coisas. Veja minhas tentativas no blog do middleheaven, já estão desatualizadas Documentar exige um esforço muito maior que programar o negocio.

Luiz_Aguiar · Março 8, 2013, 1:45pm

Nesse caso o melhor mesmo é fazer na medida certa.

Precisou de documentação?Documenta.Mas não documenta apenas pra encher linguiça,é um tremendo desperdicio de tempo.[/quote]
E tempo = dinheiro

javaflex · Março 8, 2013, 4:58pm

[quote=sergiotaborda]

Todo o planejamento é feito mentalmente. Não se engane do contrário. É por isso que é preciso ter alguem com a visão do todo “the big picture”) ou o projeto sia torto. Não importa como vc chama a pessoa que tem esta visão, mas ela tem que existir ou não ha software. Bonecos podem ajudar a pensar, podem ajudar a comunicar, mas não são documentação.[/quote]

Eu concordo com você, deve ter o líder que concentra o maior conhecimento, mas também todos devem estar envolvidos com o todo, para se um dia o líder sair de cena um outro possa assumir sem muitos traumas e todos do time ajudado com o que cada um sabe mais.

Atualmente só trabalho com um histórico de requisitos de acordo com as solicitacoes do cliente, sempre incrementando e não alterando passado. Diagrama de caso de uso, de classes, ou estados só quando houver necessidade, ou seja, quando for ajudar num modulo complexo, nessa questão da “memória visual auxiliar” que o sergiotaborda expressou bem. SCRUM ajudou muito a “acabar” com o glamour da era burocrática. Claro que para sucesso o fonte do sistema precisa estar sempre sadio.

rafadelnero · Março 8, 2013, 6:12pm

[quote=sergiotaborda][quote=rafadelnero][quote=sergiotaborda]
Finalmente, é preciso não confundir documentação com especificação. Especificação é feito antes, documentação é feito depois. O manual do usuário é uma documentação, a lista de requisitos é uma especificação. Lá porque ambas se escrevem (tradicionalmente) no word ( são “documentos do word”) não os torna documentação. Esta distinção é onde está o cerne da resposta. Planejamento precisa de especificação, não de documentação. A especificação é mutável, a documentação é imutável ( porque ela é gerada após o fato).
[/quote]