Hacker News new | past | comments | ask | show | jobs | submit login

A developer who is new to a technology absolutely needs to read the documents. No matter how good or bad, it's important because it probably tells you a lot of stuff you wouldn't learn on your own (or that someone else will teach you wrong).

I do a lot of GCP work anymore, and the amount of devs who make service authentication way more complicated than it needs to be is really freaking high. It's clear that the people who kicked off the project are pulling blocks from SO rather than RTFM because the FM has a simple decision tree for how to use authentication. Reading through the docs could have saved these projects each hours of time, simplified deployment and reduced the security risks associated with passing around json auth tokens (or worse: checking them into VCS.




Cases where docs are not enough:

- Beginners do not understand doc's jargon, or they need to learn too much stuffs to understand it that they'd rather quit. So they end up relying on third party sources/implementations

- No English knowledge and no translations


I agree with the criticisms, my point is that there are many beginners in a state where the most rational or practical choice is to sacrifice quality by following third party resources.

I have a spanish-speaking group where me and others teach beginners programming, and many of them cannot use the docs, whether because of a language barrier, or a lack of foundational knowledge, and all they care is to get things done, otherwise they'd get discouraged and abandon it before even starting


On the other hand: if you are developing software, you're going to have to be able to at least read English, and if you don't understand the jargon, that just means that your starting point isn't just the docs, but also a jargon lookup.

People generally just want to cut corners and 'be done with it' which simply results in lower quality.


I'd be surprised if the documents for any sufficiently large project did not include a "Getting started" section designed for beginners.

Everyone of your users will start off as a beginner, it behooves project creators to ensure that beginner documentation is great.


Lacking ability to read books.


Not be harsh. But if someone is going to just quit because of jargon (which everyone has to learn btw) then Sayōnara.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: