GUJ Discussões   :   últimos tópicos   |   categorias   |   GUJ Respostas

Desabafo Documentação


#1

Galera sou novo na programação consigo fazer meus aplicativos normalmente.
Uma coisa que deixa eu decepcionado são ás documentações dás linguagem os caras colocam um monte de métodos, interface, constante etc e não simplificam com exemplos esses engenheiros ou programadores não sabem ensinar é mesma coisa de dá uns pedaços de ferro, plásticos e Borracha e mandar eles construir um carro com certeza o melhor e mais inteligente não iria conseguir, pra eles é fácil eles estão na elaboração da linguagem desde começo sabem o que está por trás de cada métodos.


#2

De que linguagem está falando que não tem boa documentação? Você está sendo obrigado a trabalhar com ela? As que trabalhei até hoje são bem ricas em documentação.


#3

No geral todas são assim um exemplo disso são os blogs e fórum que ajuda mais que a documentação.


#4

São formas diferentes de conteúdo, a vantagem da documentação na linguagem é de tê-la no intellisense, não precisando sair da edição de código, e a documentação do site oficial abranger tudo que é possível. Cada conteúdo tem sua vantagem, logicamente blogs costumam facilitar mais por focar em caso específico, e forum pode responder exatamente o que uma pessoa perguntou.


#5

A documentação de linguagens de programação não costumam ter o objetivo de ensinar, mas sim de ser referência quanto à sintaxe, classes, métodos, funções e afins. Algumas são mais didáticas que outras, mas poucas vão a fundo. Se você tentar estudar pela documentação, pode se decepcionar mesmo.

Abraço.


#6

Exatamente, esse é ponto-chave, documentação é para servir de referencia para quem já está trabalhando, não é para ensinar, não é voltado para didática.


#7

Prezados os caras que fazem uma nova biblioteca deveriam se preocupar como implementar para a linguagem crescer, fica muito abstrato eu falar faz um bolo com ovos e farinha existe mil maneiras de fazer e vários tipos de bolo, o problema que eles não exemplificam.


#8

Nesse caso não é culpa da “linguagem”, mas de quem fornece a biblioteca. Antes de pagar por uma biblioteca verifique se tem boa documentação. Se é de graça ai já quer demais né, mas as mais consagradas geralmente tem ótima documentação por receberem investimento.


#9

Pois é, a documentação geralmente apresenta os Componentes, e não explica como Combiná-los e usá-los em conjunto para obter uma determinada solução. Mas às vezes você encontra na Documentação alguns exemplos de como os projetistas esperam que você Combine os Componentes e o resultado que obterá.

Quando você quer uma Solução específica, tem que pesquisar na internet, e em blogs/fóruns eles vão te mostrar como Combinar os Componentes para gerar a Solução que você quer. Mas o que acontece se a Biblioteca for bem desconhecida? Aí você não consegue encontrar na internet algo que te atenda, e isso complica bastante sua vida.

Portanto, acredito que seria melhor se as Documentações tivessem várias Soluções prontas onde você pode pesquisar na Documentação a Solução que você precisa, e, ao encontrar você teria aquela “receita de bolo” mostrando quais Componentes usar e como Combiná-los; e os Componentes usados (as Classes, Interfaces, Métodos, etc.) teriam referência para as “receitas de bolo” nas quais eles são utilizados.


#10

Isso mesmo Douglas, cara tão fácil criei uma classe nova com certeza eu tenho em mente algumas formas de utilização e como aplicar, acho que não custa eu fazer algumas aplicações para demostrar sua eficácia.


#11

Concordo quando existe investimento para isso, mas custar custa, qualquer tempo é dinheiro.


#12

Concordo quando existe investimento para isso, mas custar custa, qualquer tempo é dinheiro.

É verdade que custa, e bastante. Mas e quem for usar a biblioteca? Quanto tempo essa pessoa vai precisar gastar para entender como usá-la e como solucionar seus problemas com ela? Se a pessoa não entender direito ela pode até usar incorretamente e ter problemas! Ou seja, o custo para quem for aprender e usar a biblioteca pode acabar sendo bem maior do que o custo que haveria sobre quem poderia ter feito explicações e exemplos sobre como utilizar a biblioteca.


#13

Nesse caso o custo é seu de gastar para entender, não de quem disponibilizou a biblioteca de graça. Logicamente ele já sabe utilizar para uso próprio.

Você pode solicitar suporte também dependendo do caso.

Mas afinal de que biblioteca por exemplo vocês estão reclamando?


#14

Mas pensa bem, se a biblioteca é desenvolvida por um time, cada pessoa vai ter que explicar pra outra o que fez e como utilizar? Não é melhor criar e armazenar essas explicações? E se até quem fez acabar esquecendo como utilizar depois de alguns meses? E se o sistema for passado para outra empresa, vai ser necessário explicar a biblioteca pro novo time?


#15

Num time bem dividido seguindo metodologia ágil não precisa disso, pela convivência no dia a dia naturalmente todos sabem o que o outro faz, basta conversar. Agora se o sujeito vai disponibilizar a biblioteca para uso externo, deveria ter documentação, se não tem é porque não pretendem ter retorno com isso, apenas cederam a biblioteca. Você como usuário deveria buscar outra biblioteca que tenha documentação.


#16

E o que acontece um bom tempo depois que o sistema foi feito e surgiu o interesse de alterá-lo ou reutilizar partes dele? E se quem fez não se lembra bem de como funciona e como usar (isso já aconteceu muito comigo, principalmente quando o modo de usar é Complexo, envolvendo compor Objetos da maineira certa, registrar as coisas certas nos lugares certos, etc.)? E se as pessoas da equipe ágil que conheciam certas partes da biblioteca já saíram da Empresa?

Eu acho que no futuro o preço a pagar por não ter feito e armazenado exemplos e explicações sobre a biblioteca poderá ser - muitas vezes - maior que o custo de tê-los feito antes.


#17

Só para ambientes que tem problemas com alta rotatividade de pessoal, tipo fábrica de software, ai sim tem que ficar documentando tudo, seguindo N padrões, N siglas, etc. Mas se por exemplo um mesmo time de 5 pessoas se mantiverem juntas por mais de 5 anos com uma ou duas perdas, isso é desnecessário.


#18

E como eles vão fazer para reutilizar as bibliotecas que já criaram há muito tempo?

Quando você cria um conjunto de Classes para serem usadas juntas de uma forma relativamente complexa, você consegue se lembrar de como usar aquilo alguns meses (ou mesmo anos) depois? Sai mais rápido para você relembrar de como usar do que ter feito e armazenado explicações?


#19

Os integrantes que já conhecem vão passando conhecimentos para o novo integrante, naturalmente no dia a dia.

Dificuldade em dar manutenção por não lembrar é desculpa para código mal feito.


#20

O propósito da documentação de uma linguagem não é ensinar a programar. É como o @javaflex falou, a documentação serve como referência para quem já sabe programar e está com dúvida na sintaxe, nos tipos de retorno ou no comportamento específico de um método ou classe. Resumindo, a sua crítica não faz sentido, por uma série de motivos:

  1. É muito genérica e difusa. Assim não tem como fornecer um contra exemplo do que é uma boa documentação.
  2. Você está simplesmente reclamando de algo que as documentações não prometem entregar
  3. Sua proposta do que deveria ser feito no lugar também não é clara, ou seja, você critica mas não sugere nada como melhoria

Enfim, a impressão que eu tenho é que você quer programar orientado a copiar-e-colar pegando o que já tem pronto na Internet.