Executando verificação de segurança...
7

Ler documentação: como isso me ajudou a programar melhor!

Eu exitei bastante em iniciar esse conteúdo por diversos motivos e um desses motivos é que eu estou na minha segunda experiencia profissional, e do ponto de vista logico eu ainda sou um iniciante, mas queria compartilhar com vocês uma experiencia recente que tive trabalhando pela primeira vez com um time de especialistas em uma grande empresa e também apresentar alguns fatos interessantes e algumas sugestões que me fizeram aprender a programar de fato.

1) Documentação é muito superior a assistir um curso

É obvio que isso não se aplica a tudo, não é uma regra geral de fato, mas acredito que todo programador com experiencia, já assistiu algum curso e pensou "esse cara ta apenas lendo a documentação em voz alta" e bom acredito que de fato isso aconteça na maioria dos casos, existem algumas exceções onde algum professor com uma didática diferente consege explicar um fato que parecia confuso, mas ai que entra a questão desse topico a documentação tem que ser a sua primeira opção sempre, a documentação tem que ser sua primeira ferramenta de busca, em seguida artigos, vídeos etc. O argumento por traz disso surge do fato de que no mercado de trabalho o foco é solucionar problemas de forma limpa, rápida, escalável, e sofisticada. Quando alguém assiste um video ou um curso como primeira opção, ela está abrindo porta para códigos desatualizados, destoante da regra de negocio, e isso implica na segunda questão que vou falar agora.

2) Documentação tende a sempre estar atualizada

Esse fato se aplica no geral as documentações oficiais, existem muitas documentações boas na internet mas é sempre importante verificar as datas de atualizações. Como eu havia abordado no tópico anterior, é ideal que no mercado de trabalho o sistema esteja sempre utilizando soluções modernas, isso se aplica a situações como por exemplo: vamo supor que você esteja com um problema que foi solucionado pela documentação há anos, vai bastar uma rápida lida no contexto que você esta inserido e pronto problema solucionado da forma mais moderna possível.

3) Dicas uteis para começar a criar o habito de ler documentação

Entenda a documentação como uma receita, você ler, interpreta, pega os ingredientes e aplica, se queimar ou não ficar bom.... então nesse caso não estamos falando de comida você terá que ler e aplicar de novo. Normalmente as documentações costumam ter uma área para tutorial,e uma de fato para a documentação, o tutorial costuma dar uma breve introdução, e ensina normalmente a fazer o setup da tecnologia que você esta utilizando(aqui você já teria que assistir umas quatro ou cinco aulas de algum curso meia boca por ai). A documentação em si costuma ter uma parte onde explica e demonstra os conceitos, e uma outra parte com descrições de cada funcionalidade especifica da tecnologia, a demonstração de conceitos é perfeitamente util para aprender, porem oque me ajuda no dia a dia são as descrições das funcionalidades. Um exemplo disso é minha constante pesquisas na documentação do django sobre models e querySet, coisas que não faz sentido pra mim entender o conceito pôs são simples e facilmente entendível , mas a utilização e os parâmetros fazem mais sentidos pro meu dia a dia principalmente em questões especificas da regra de negocio do projeto, onde cabe a mim desenvolvedor procurar nas funcionalidades existentes formas de se adaptar á minha realidade e ao oque preciso fazer.

4) Como identificar se a documentação é boa ou ruim

Esse ponto deixei por ultimo por um motivo obvio, ele é completamente pessoal e sim eu ja vi gente defendendo ou criticando de forma injusta documentações só pelo fato de não ter entendido a tecnologia,Mas eu vou separar alguns pontos que pessoalmente fazem eu digerir melhor uma documentação.
> Documentação que tem exemplos claros e objetivos
Um exemplo de documentação com bons exemplos é a do React Native que tem uma clareza na interface do site, e além disso ótimos sandbox onde você consegue entender facilmente oque cada parte daquele código ta fazendo.
> Documentação com uma guia simples
Um exemplo de documentação que apesar de boa tem uma guia completamente caótica é a do django, apesar de super completa, ela faz você facilmente se perder em tantas possíveis direções e diferentes paginas do mesmo assunto que a documentação vai, normalmente a documentação oficial é essencial mesmo que desagradável que você leia, porem em situações especifica procure documentações que mesmo não sendo a oficial são mais digeriveis. Um exemplo de ótima documentação alternativa que é facilmente inteligível é a w3schools.

A principal diferença de um especialista pra um Júnior

Obviamente existem mais diversos motivos para se ler documentação oficial ou não oficial, mas em geral com essa minha experiencia profissional com especialistas eu cheguei a conclusão que de fato o poder de conhecimento e que aquele profissional tinha em relação aos demais era exatamente oque esse artigo aborda: A leitura da documentação te torna naturalmente um especialista. Espero que esse artigo instigue aos mais novatos á criarem esse habito e que ajude de alguma forma quem ainda não teve esse interesse por ler documentações.
Carregando publicação patrocinada...
4

Concordo com alguns pontos, discordo de outros.

Concordo que ler documentação é importante. Mais que isso, é essencial, obrigatório ler pelo menos uma vez antes de usar qualquer coisa.

Um erro muito comum é a pessoa usar alguma coisa e reclamar que não aconteceu o que ela achava que deveria acontecer. E gasta horas tentando descobrir porque não está funcionando. Aí você vê na documentação e lá explica que essa coisa faz algo completamente diferente. Se tivesse lido antes de usar, não perderia esse tempo.

Documentação também é uma ótima referência para quando você não lembra direito algum detalhe (O que era esse terceiro parâmetro? Essa função faz o que se der erro?). Em vez de quebrar a cabeça e ficar na tentativa e erro, é muito mais simples consultar a documentação.

Mas eu discordo que "A leitura da documentação te torna naturalmente um especialista". Pra ser especialista tem que ter muito mais que isso, ler a documentação é apenas um dos muitos passos a serem dados. Até porque muita documentação só descreve o que algo faz e dá alguns exemplos sobre o mecanismo, mas ela não tem tudo que é necessário para te tornar especialista. Isso só vem com anos de experiência e estudo, a documentação é só uma parte disso - importante, claro, mas ainda sim, uma parte. Tem coisas que só se aprende na prática, que manual nenhum vai te explicar.

Também discordo sobre o w3schools. Esse site já foi pior, hoje em dia melhorou um pouco, mas eu ainda acho um dos piores. Claro que depende da tecnologia, mas eu geralmente encontro opções melhores. Por exemplo, para Java, Python e C#, a documentação oficial é muito boa. Para JavaScript, HTML e CSS, a MDN é bem completa e abrangente. Muitos frameworks possuem documentação oficial e tutoriais que são mais que suficientes. Claro que tem casos e casos, mas em geral, as linguagens e frameworks mais mainstream possuem algum material minimamente decente. Deixei de consultar o w3schools há tempos (às vezes eu volto lá pra conferir, e vejo que ainda prefiro os outros sites).

Apesar disso, de forma geral concordo com o ponto principal: ler documentação é um hábito que todo desenvolvedor deveria ter.

2

E aí pergunta no Stack Overflow algo que já está disponível para ela. O que não tem problema, se a pergunta for bem feita. Mas geralmente o mesmo motivo, de atitude, que leva a pessoa a não ler a documentação é o que leva a pessoa a fazer uma pergunta ruim no SO, ou outro lugar. è um problema de falta de comprometimento.

Ler a documentação de forma comprometida ajuda muito a pessoa programar melhor, evoluir, criar as condições para cosias mais importantes ainda que ler a documentação, que é o básico do básico, e que não costuma ser feito.

Ajuda até melhorar, espero, na interpretação de texto, que sinto estar cada vez pior. E se não melhorar, aí tudo está perdido. Eu semrpe falo que os maiores fundamentos que o programador precisa é matemática e comu nicação e expresão. Se a pessoa é ruim demais nisso, ela será igual em programação.

Docum entação não ensina a pessoa programar. Ela ensina como usar um mecanismo. Se ela for boa, em muitos casos não é. E pior, precisa aprender ausar documentação, porque em geral o exemplo está lá apenas para ilustrar o mecanismo, não é uma receita de bolo para copiar e colar e usar. A documentação pode ajudar a pessoa programar mais errado ainda, novamente, se ela não tiver a atitude certa.

Acreditar que a documentação torna alguém especialista camufla a real necessidade e tende fazer a pessoa se contentar com pouco, e evoluir pouco como consequência.

Escolher a documentação certa também é importante, e depende de experiência e aprendizado anterior, além de... interpretação de texto. O W3S nunca foi uma boa escolha, ainda que não causa tanto problema como causava antes.

Documentação estilo wiki são perigosas. Material em Português costuma ser pior que em Inglês, inckuyindo documentação. Exemplos bem claros são do PHP e a MDN.

De qualquer forma, se as pessoas passarem a ler documentação muda absurdamente o estado que estamos na área.

Farei algo que muitos pedem para aprender programar corretamente, gratuitamente. Para saber quando, me segue nas suas plataformas preferidas. Quase não as uso, não terá infindas notificações (links aqui).

1
1

"esse cara ta apenas lendo a documentação em voz alta", eu tive esse mesmo pensamento quando pesquisei como resolver um problema no w3school,lá percebi que a solução apresentada era exatamente igual aquela apresentada no curso, ou seja, o curso só repetiu o que estava na documentação.
PS: não estou dizendo que cursos são ruins, há alguns incríveis, mas outros nem tanto.

1
1

Uma ótima dica!!

É o que eu costumo falar para os estagiários/juniors, é só ler a Doc que tem tudo lá escrito como utilizar e o que precisa utilizar, é só ler.

As pessoas já tiveram o trabalho de fazer a doc justamente para as pessoas entenderem como utilizar a biblioteca/framework, então leia a doc.

Ou então se achar algum problema, procure ele nas issues da biblioteca/framework, normalmente alguma outra pessoa já passou por este mesmo problema e alguém da comunidade conseguiu achar a solução para o mesmo.

1

Cara um tempo atrás eu estava com um problema com o Spring Security, procurei o que precisava em praticamente todo canto da internet e o único que me apresentou o que precisava era justamente a documentação oficial. Basicamente se eu tivesse me atentado ao que você disse nos tópicos 1 e 2 teria resolvido o problema muito mais rápido.

1

Realmente, eu concordo com você, eu mesmo tenho um serio problema com documentação, algumas documentações ao meu ver são muito dificeis de entender pelo menos para mim, eu fico perdido dentro da documentação do GTK, tento aprender mas é bem complicado, estou acostumado com documentação com exemplos estilo PHP, ontem mesmo que eu fui entender uma parte da DOC do GTK vendo live do Georges Stavracas, mas tem algumas DOC que eu tenho problemas de achar as coisas e outras de compreender o que o codigo faz, exemplo: this.abrirJanela(fechadura(CHAVE_EM_CIMA_MESA)) o codigo poderia ser assim ou assim this.abrirJanela().fechadura(CHAVE_EM_CIMA_MESA), fico meio confuso nessas partes.

1

Bastante verdade isso. Um dia eu tava com problema de executar um comando pra criar migration no TypeORM e encontrei logo de cara na documentação. Além disso, outro dia tava fazendo uma aplicação que precisava de um seed e foi só ler de novo. É muito bom mesmo ler documentação.

1

Eles ajeitaram a documentação deles? Eu horrível a documentação deles, so uso TypeOrm agora se for obrigatório mesmo.

Da ultima vez que precisei da documentação deles, eles tinha lançado uma nova versão do Type a alguns meses que quebrava muita coisa na versão anterior e a documentação deles tavam desatualizada, perdi horas para resolver, eles tem tanta forma de fazer a mesma coisa, que foi difícil achar algo que desse certo pro meu caso, tenho um impressão que o projeto está ficando abandonado, pode ser so impressão mesmo ja que não to mais acompanhando a comunidade do TypeOrm

1

Pior que é verdade mesmo. Eu tive problemas em atualizar conexão com BD porque tava tudo deprecated na versão nova, mas eles ajeitaram a documentação sim. Ainda é bem resumidona, mas tá atualizada.

1
1

Achei os seus argumentos muito sólidos! claro que para se tornar um especialista exige anos de prática também.

Sou um novato em java e não tinha lembrado de ler a documentação. Depois desses argumentos, vou ler a documentação do java urgente!

So tenho uma dúvida, você recomenda ler a documentação em do início ao final ou em alguma outra ordem específica?