How can I get through very long and very dry, but also very useful technical documents when learning a new tool?

Question

Vulkan is a very useful API for rendering projects, and I would like to learn how to use it as it opens up new possibilities for doing some rendering tricks much more efficiently than in OpenGl.

I am having significant trouble learning it, however. It is a very complex API with many essential details. These details, while useful, are not interesting enough in and of themself to reliably hold my attention for long periods, even if I put in significant effort. I find when I go through the written tutorials that I get very distracted by almost anything.

For example, when I was reading about its mechanism for selecting a GPU in a multi-GPU system instead of focusing on the syntax that I want to learn, I ended up thinking about all the implications of such a selection existing, compared to the fact that it does not in OpenGl. Distractions such as that end up drastically increasing the time that I need to spend on the reading, and skimming is not an option either as the details really are important.

There are also diminishing returns as my ability to use will power to remain focused diminishes much more quickly than I would like it to (I can only get through maybe ~10 pages of this reading in a single sitting while maintaining the focus that I feel is necessary.)

This problem is not unique to Vulkan. I had the same problem, but to a much lesser extent, when learning OpenGl. In that instance, I was able to find video tutorials that explained the necessary concepts very succinctly. This helped both because the explanations were more succinct, with only the necessary information (including theory when appropriate) to use the API (and I could look at written alternatives when I wanted more details).

When I attempted this for Vulkan, however, the only video tutorials that I could find were both outdated and contradicted the text tutorials in a few places, making me very weary of using them as I may pick up bad practices or outdated Vulkan. Video tutorials also work well for me as they keep on moving even if I get temporarily distracted, thus pulling my attention back. When reading, if I get distracted I automatically stop reading.

I would also like to note that this isn't an issue of lazyness; I am willing to put in significant time to do it, but I find that my ability to focus is quickly diminishing.

As such, I ask: How can I learn Vulkan (Ideally, the advice will be applicable to other similar tasks as well) reasonably efficiently and how can I counter the described road-blocks?

Answer 1

As someone who has read through the OpenGL and Vulkan specifications, I've always found that it's best to digest them in bite-sized chunks. Never try to binge on the whole document in one day. Indeed, the kind of "distraction" you're talking about, thinking about the ramifications of a particular API, is a good thing; it helps the knowledge stick.

There are two ways to read something like this, depending entirely on your familiarity with the subject matter.

If you are unfamiliar with the subject (for this Vulkan example, you would be a person who doesn't have much of an idea on how 3D graphics works), it's best to just start at the beginning.

Read a chapter of the specification. As you're reading it, try to map the concepts it talks about to things you already know. Also, try to make note of what it has aluded to (specifications are not written like reference documentation; they will often talk about concepts not yet introduced), so that when you get to that part, you'll understand how it fits in. Lastly, think about the implications of what is said in that chapter; try to wrap your brain around what it all means.

The next day, read another chapter.

If you have some familiarity with the system, then I would say it's best to start with what is familiar to you, and branch out from there. For example, if you were a modern OpenGL user who is learning Vulkan, you might start with the chapter on drawing commands.

When you jump into the middle like this, you'll hear about a lot of concepts you don't know: devices, command buffers, pipeline stages, etc. But you'll also start noticing that some of them are similar to things you do know: shader stages, primitives, etc. That helps build a translation layer between what you know and what you don't, as well as giving you some places to start learning more.

Once you have a list of Vulkan topics you don't know, then you start following links to chapters and sections that talk about them. Go to the section on command buffers, and you'll find stuff about queues, devices, and that all important Vulkan topic, synchronization. Each of these steps should be its own session of investigation.

When you do this, it's best to treat these new topics as black boxes; don't try to speculate too much about what they do until you've actually read about them. Or at the very least, if you speculate about them, be willing to readjust your speculation based on any reality you later discover.

Oh, and regardless of which way you're doing it, you should take notes. That is always helpful when dealing with complex information like this. Write down what it is you think these complex things are. If you find out that something isn't how you thought it would be, change your notes.

Answer 2

Man, I'm right there with you. I understand completely your situation, as I've been there myself many times.

The key, I find, is not reading the tutorials.

Instead, I pick a few projects - starting with something that's "hello, world" level. I google and read enough to be able to do that. Then I pick a slightly harder project - for Vulkan, maybe pick a scene of intermediate difficulty, and google and read enough to do that.

If you keep doing this, you very quickly obtain a practical base of knowledge. There are, however, disadvantages to this - obviously, there will be holes in your knowledge, and you could miss style guidelines depending on what you're looking at to write your code (e.g., when I first learned python, I came into it knowing how to program in javascript - so my first instinct was to write variable names in camelCase, and it was only after several years that I actually read PEP8 and changed to under_scores, though in my defense I didn't even realize style guides were a thing at the time).

You might even wish to go through this approach, and then read through the tutorials with the perspective of someone who's "brushing up" - this might fill in the crevices the more trial and error method doesn't fill.

If, however, you wish to fully work through the documentation straight off, I'd recommend reading a paragraph/section, and writing down something about how you'd use what you just learned about in a real program - i.e., mentally applying the small details. You want to build up a 'web' of details, with lots of connections between the nodes, so that every node is much easier to 'get to' (remember). The more you know, the more you remember (as odd/obvious as that sounds).

Answer 3

I've found that a useful trick is to have a specific project or end goal in mind. That helps to focus your attention on completing that project or goal, and gives you a purpose to think about what you're reading. It can also help you retain more of what you're reading, since you're always applying the new things you're learning.

Frequently, you'll be able to find beginner oriented projects online that you could try to build, or maybe you have some vision or project that you want to use this new technology for.

I find that having a project or goal really helps you 1) stay motivated to keep reading 2) retain the material (and have some code snippets to use later), and 3) not get lost down long rabbit holes (although this still requires some willpower).

Good luck!

Answer 4

The answers by heather and thesecretmaster are already spot-on: give yourself a project to work towards.

APIs are tools. It doesn't really make sense to "learn an API" by itself, in the same way that it doesn't make sense to "learn a hammer" by itself. You should be figuring out how a specific tool solves a specific problem. For that, you need a problem first.

Another suggestion I haven't seen in any of the existing answers is: write your own documentation as you read through the existing documentation.

If you read through a page of their documentation, try to boil it down to a bare minimum. What was the takeaway? It's probably a sentence or two, or a snippet of code. Start your own documentation that collects these takeaways.

When you have enough of these takeaways, you can start thinking about: How would you organize the documentation differently? What should "hello world" look like? What topic should come right after that?

I highly recommend publishing your new and improved documentation somewhere: to a personal blog, as a pull request to the original documentation, or as answers on Stack Overflow. But even if you don't publish them, the process of coming up with them in the first place can be extremely educational.

Answer 5

I am right there with you; I find it incredibly difficult to work through something substantial and new without disappearing down many little rabbit holes.

Here's a simple idea: have you considered just making a list of "questions to answer"? It would be for items that you want to explore in order to flesh out your understanding, but aren't in the main thread of your learning.

Items on the list would resolve in one of four ways:

1. It graduates to the main thread when you stop understanding what is going on.
2. You come to understand it over time without doing an explicit research, just from context and osmosis.
3. Through devoted time (perhaps at the end of a session, when your attention is starting to flag anyway), you eventually fill in the hole with some side-research.
4. It turns out to be unimportant enough that it never comes up again, and can safely be ignored.

The most important things, I think, are not to go down every rabbit hole you see right away, and to reserve some time to go through the list from time to time and fill in some of the missing puzzle pieces.

Answer 6

Almost all of my advice is from Courseras "Learning how to learn" which I highly recommend.

1. Take breaks. Study for maybe 20 minutes then take a short break. Do something physical in these breaks if possible like some squats, push-ups or go for a short walk.

2. Make sure you have plenty of fresh air. High levels of CO2 and low levels of O2 make us tired.

3. Take notes. After reading a section write down what you learned. You might even make these a blog post or do a short talk about it.

4. Do practical things. This was recommended by others: Instead of just brute force learning, pick a task and learn what you need to learn for that task. This helps with motivation and also by linking the knowledge to other experiences making it easier to remember.

5. Take notes about what to learn. You mention getting sidetracked often by looking stuff up that is not directly related to what you are trying to learn right now. Use your notes to write down what you'd like to look up then look it up when the time is right.

6. Repeat. We can't internalize complex knowledge directly. We need to repeat and practice it. With software APIs, katas are a proven way to do that. When you learn something new, make a tiny project putting the knowledge to use. This should take about 30min. Repeat this project after a short break. Then again maybe on the next day. Repetition with increasing time in between makes sure the knowledge ends up in long term memory.

Answer 7

One very simple technique I have found useful in processing information which I do not understand easily, is to review it multiple times, preferably in different sessions.

You said:

(I can only get through maybe ~10 pages of this reading in a single sitting while maintaining the focus that I feel is necessary.)

and this implies to me that you consider the reading something to do once. I have found that reading the same material again and again (ideally with sleep periods between these sessions, but at least with some rest), allows me to understand things that I cannot understand on the first reading.

I understand that this makes your reading process even longer, but it is one way to get the job done, and at least the enhanced understanding of subsequent reads can provide you with some more motivation to carry you through.

One suggestion here could be to split your time between (a) reading at the "head" of your progress through the documentation, and (b) re-reading parts of the documentation you've already read previously, and then possibly (c) re-reading parts you've already re-read, i.e. re-re-reading.

On second and third readings, you brain will be able to find deeper connections between the seemingly disparate details, and the material will seem less "dry".

Answer 8

I do read one time fully, without worrying about remembering. And then I pick a beginner project and start learning by doing. There is no way to read and remember all those dry details. But you will remember where to look when you get stuck in your projects. I was quite successful with this method, many times.

Answer 9

For example, when I was reading about its mechanism for selecting a GPU in a multi-GPU system instead of focusing on the syntax that I want to learn, I ended up thinking about all the implications of such a selection existing, compared to the fact that it does not in OpenGl.

Yes humans can not be programmed. This is not a good way to learn. You are being distracted, because what you are reading is not useful. Syntax is not the important bit.

As an experienced programmer, I just look it up as I go. I need to find something that gives me a good overview of what it does (not how), what the philosophy of it is. Then I just get on with it (very slowly at first), and look stuff up just-in-time. Sometimes I look stuff up more than once.

Answer 10

Suggestions:

• Do not just read the API, but focus on actually doing what you want to do. I don't know Vulcan, but many other APIs, language specifications, protocol specifications etc. You can skim them quickly to see what the API has to offer (the general topics, architectural overview etc.). But then try to use the API. At first, you will immediately hit your first roadblocks. Then go and try to overcome each individual block, by delving into the dry documentation. Your carrot is the small goal you are currently trying to achieve. This is a good point for StackOverflow as well... if you have very concrete problems, you can just ask.
• Avoid tutorials. Exceptions notwithstanding, they are the devil for building deep know-how, in my experience and strong opinion. They are often outdated; they represent the usual limited understanding of the author. They are specialized to whatever the author needed at the moment, and his opinions about how APIs should be used. About the only good case for tutorials is for a short "hello world"-style piece which gets you running from a blank slate (i.e., gives you the bare minimum commands to compile your first program or whatever you're doing). But as soon as you have even the slightest working bit of program, get rid of them ASAP.
• Do not feel that you are somehow inferiour or whatever. In my long experience, most people do not want to, or actually cannot read specifications/reference documentation. You are in good company. But don't give up...

Good luck.

Answer 11

You're not alone.

Try to focus on "what do I need to know now?". On first reading, you need to understand the basic concepts. Try to find the sections of the document that explain them. (Many technical documents are bad at explaining them, or don't put the explanations in the obvious place.) If you find some text that you don't understand because you don't know what the words mean, stop reading (there's absolutely no point carrying on) and try and find where in the document the words are explained.

If you find a section that's all about edge cases (how does the system handle division by zero), recognise that and skip it. You don't need to know that right now.

On your first reading, try not just to absorb the content, but also to form an assessment of what kind of document you are reading. What kind of reader is it aimed at, and is that you? Which is going to be more useful, the examples, or the formal narrative? How careful is the writer about explaining things? Does it use terminology consistently and accurately? Understanding how the writer's mind is working can help your reading: if you come across a word like "specify" or "denote", are they using it carefully or carelessly?

Think carefully about how to balance reading with hands-on experimentation. Some people start the hands-on too early, before they understand the concepts; that can lead to you drawing false conclusions about the system's behaviour, and to frustration that you can't make anything work. But if the documentation has "Hello world" examples to take you through things gently, then try them out. Not only will it give you confidence that you're following the text and making progress, it will keep you fresh and stop you falling asleep.