3 ms·

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

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

oneplane 6y ago
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.
bordercases 6y ago
- Tough luck - this is actually a trap for beginning learners so although there is wisdom in learning enough to get the job done, if they rather quit than progress in their knowledge, and the knowledge is foundational for much of their work, they are setting themselves up for long-term failure. - Fair point, English is still a lingua franca so over time this issue nils out.
pjmlp 6y ago
Lacking ability to read books.
mywittyname 6y ago
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.
madacol 6y ago
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
net_greybeard 6y ago
Not be harsh. But if someone is going to just quit because of jargon (which everyone has to learn btw) then Sayōnara.

oneplane 6y ago

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.

bordercases 6y ago

- Tough luck - this is actually a trap for beginning learners so although there is wisdom in learning enough to get the job done, if they rather quit than progress in their knowledge, and the knowledge is foundational for much of their work, they are setting themselves up for long-term failure. - Fair point, English is still a lingua franca so over time this issue nils out.

pjmlp 6y ago

Lacking ability to read books.

mywittyname 6y ago

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.

madacol 6y ago

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

net_greybeard 6y ago

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