2 ms·
Ask HN: How to read documentation?
I searched on HN how to read documentation. In my opinion it is not straightforward and I haven't found many good tutorials on it. More importantly for CS students, they don't learn it in their universities and neither have I. I learned it in an ad-hoc fashion through some off-hand comments from people but I want to improve.
Take the jQuery documentation on .children() for example [1]. you see square brackets [ ]. Does that signify an array? I know that's not the case but only through an off-hand comment. Also, what does it exactly return? It doesn't seem immediately obvious to me unless I try it out in the JavaScript console.
My question on how to read documentation also includes the sub-questions:
1. What are examples of good documentation?
2. What are examples of bad documentation?
3. Are there examples of sub-cultures in documentation (e.g. the manpages have different conventions than the docs on jQuery and the docs on Sequelize are different again).
4. What are things that are not so straightforward in learning how to read documentation?
5. What are not so straightforward symbols regarding reading documentation? An example answer on question 5 would be: the square brackets [ ] don't signify an array, but signify optional parameters/arguments in function definitions / function calls.
If there are amazing learning resources on how to read documentation or if you have a comment on how you learned to read documentation that would be appreciated as well.
[1] https://api.jquery.com/children/
- brudgers 8y agoFor what it's worth, I think it's both a habit and a skill. Developing both or either requires practice, but the more you do the easier and more productive it gets. Like you, when I read programming documentation, typing the examples into an interpreter seems to make the concepts stickier. I think it's a habit I've developed from reading documentation. My experience is that notation is usually described in the introduction.