I'm working on the "research" section of the debugging zine today. so far I have:

* read the library's code
* learn one small thing
* look at github issues
* spend 5 minutes reading the docs
* try to find a deep dive blog post explaining your exact bug in detail

what's missing?

I also want to talk about reading the documentation, but I'm having trouble figuring out a way to do it that isn't boring or condescending.

Are there practical strategies for reading documentation more efficiently/effectively?

Follow

@b0rk Do not read what the documentation is saying, but try to infer things about whoever was writing the documentation. E.g. the total lack of statements on some topic usually mean that either this topic is unimportant for some obvious reason, or it has totally escaped the authors' minds. Similarly, often one can extrapolate precision levels of one part of the documentation onto others (which makes looking at documentation for a part you know very well useful).

If you lack some sort of fundamental understanding about general design of the thing (e.g. its data model, which things are mutable, what identifiers of remote objects are assumed to persistently point at the "same" object, etc.) then often looking for the answer to that question in the documentation of fundamentals is less expedient than picking one feature that (or its usage) will have to depend on that property and doing a depth-first search on reference documentation for that feature/API call/...

Sign in to participate in the conversation
Qoto Mastodon

QOTO: Question Others to Teach Ourselves
An inclusive, Academic Freedom, instance
All cultures welcome.
Hate speech and harassment strictly forbidden.