Answers.Body: <p>The answers by <a href="https://cseducators.stackexchange.com/a/5495/2068">heather</a> and <a href="https://cseducators.stackexchange.com/a/5494/2068">thesecretmaster</a> are already spot-on: give yourself a <strong>project</strong> to work towards.</p>
  
  <p>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.</p>
  
  <p>Another suggestion I haven't seen in any of the existing answers is: <strong>write your own documentation</strong> as you read through the existing documentation.</p>
  
  <p>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.</p>
  
  <p>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?</p>
  
  <p>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.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2022-02-18T20:20:46.467Z
Answers.Text: As well as writing one's own documentation, as I work on a simple example that uses the tool/API I am trying to learn, I annotate (heavily) the code that indicates what component of the language I was using at that point in my code and WHY I was using it. Then test, test, test each bit of code as I add a little bit more.
Answers.UserDisplayName: Clive Long
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-28T00:58:24.470Z
Answers.LastActivityDate: 2019-03-28T00:58:24.470Z
Answers.UserDisplayName: Kevin Workman
Answers.Body: <p>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. </p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-29T10:34:07.010Z
Answers.Text: Welcome to [cseducators.se]! This answer seems to have good potential. could you perhaps expand it with slightly more concrete examples? Either way, I personally find this to be quite a good answer. I sure hope we'll see more content such as this answer from you again :)
Answers.UserDisplayName: ItamarG3
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-29T17:52:37.323Z
Answers.Text: @ItamarG3 Thank you, flattered :) I think the answer already explains my approach totally I'm not sure how can I expand it. But if you have a question or you think something is unclear, I can gladly include an answer for it. Thanks for your time.
Answers.UserDisplayName: ferit
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-28T19:09:25.303Z
Answers.LastActivityDate: 2019-03-28T19:09:25.303Z
Answers.UserDisplayName: ferit
Answers.Body: <blockquote>
    <p>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.</p>
  </blockquote>
  
  <p>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.</p>
  
  <p>As an experienced programmer, I just look it up as I go. I need to find something that gives me a good overview of <strong>what</strong> 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.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-28T19:55:55.880Z
Answers.LastActivityDate: 2019-03-28T19:55:55.880Z
Answers.UserDisplayName: ctrl-alt-delor
Answers.Body: <p>Almost all of my advice is from <a href="https://www.coursera.org/learn/learning-how-to-learn" rel="nofollow noreferrer">Courseras "Learning how to learn"</a> which I highly recommend.</p>
  
  <ol>
  <li><p>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.</p></li>
  <li><p>Make sure you have plenty of fresh air. 
  High levels of CO2 and low levels of O2 make us tired.</p></li>
  <li><p>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.</p></li>
  <li><p>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.</p></li>
  <li><p>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.</p></li>
  <li><p>Repeat.
  We can't internalize complex knowledge directly. 
  We need to repeat and practice it.
  With software APIs, <a href="https://en.wikipedia.org/wiki/Kata_(programming)" rel="nofollow noreferrer">katas</a> 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.</p></li>
  </ol>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T07:45:55.033Z
Answers.LastActivityDate: 2019-03-27T07:45:55.033Z
Answers.UserDisplayName: Jens Schauder
Answers.Body: <p>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.  </p>
  
  <p>You said:  </p>
  
  <blockquote>
    <p>(I can only get through maybe ~10 pages of this reading in a single sitting while maintaining the focus that I feel is necessary.)  </p>
  </blockquote>
  
  <p>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.  </p>
  
  <p>I understand that this makes your reading process <em>even longer</em>, 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.  </p>
  
  <p>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.  </p>
  
  <p>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".</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T18:15:19.250Z
Answers.LastActivityDate: 2019-03-27T18:15:19.250Z
Answers.UserDisplayName: Luke Griffiths
Answers.Body: <p>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.</p>
  
  <p>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.</p>
  
  <p>Items on the list would resolve in one of four ways:</p>
  
  <ol>
  <li>It graduates to the main thread when you stop understanding what is going on.</li>
  <li>You come to understand it over time without doing an explicit research, just from context and osmosis.</li>
  <li>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.</li>
  <li>It turns out to be unimportant enough that it never comes up again, and can safely be ignored.</li>
  </ol>
  
  <p>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.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-26T19:09:56.727Z
Answers.LastActivityDate: 2019-03-26T19:09:56.727Z
Answers.UserDisplayName: Ben I.
Answers.Body: <p>Suggestions:</p>
  
  <ul>
  <li>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 <em>can</em> skim them quickly to see what the API has to offer (the general topics, architectural overview etc.). But then try to <em>use</em> 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.</li>
  <li>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.</li>
  <li>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...</li>
  </ul>
  
  <p>Good luck.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T10:21:43.727Z
Answers.Text: The comment about tutorials is valid for many hastily-put-together articles found on the web, often written by someone who is no expert and wants to share what he/she has just learned. But there are also tutorials that are very carefully designed, crafted, and reviewed by experts. You need to be able to recognise the difference.
Answers.UserDisplayName: Michael Kay
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T12:17:01.777Z
Answers.Text: @MichaelKay, I've added an "exceptions notwithstanding". As a counterexample to your counterexample I'll mention a once de-facto Ruby-on-Rails tutorial, which was in fact a very long and extremely well written e-book/website. Both didactically great; written in clean and well understandable tone. Exactly what you propose. The problem? It is for Rails 3. Rails 4+ are radically different. Most of the info in that tutorial is not only replaced by more modern stuff, but doesn't work anymore, outright. The problem? As it's so good, it still often turns up quite high in searches, and it is really...
Answers.UserDisplayName: AnoE
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T12:18:27.840Z
Answers.Text: ... tempting and easy to fall into the trap of using/studying it; eventually getting ever more and more confused due to the fact that things mysteriously fail to work over time. But really worst of all; even the parts that still work follow an outdated mode of operation for several parts of that ecosystem. All in all, a developer following that as his main source at the beginning sets out with a (in part radically) wrong understanding, laying plenty of obstacles in the way.
Answers.UserDisplayName: AnoE
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T12:53:06.820Z
Answers.Text: Yes, out-of-date information is always a problem on the web.
Answers.UserDisplayName: Michael Kay
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T10:00:11.377Z
Answers.LastActivityDate: 2019-03-27T12:14:46.110Z
Answers.LastEditDate: 2019-03-27T12:14:46.110Z
Answers.UserDisplayName: AnoE
Answers.Body: <p>You're not alone.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p>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?</p>
  
  <p>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.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T10:16:20.220Z
Answers.LastActivityDate: 2019-03-27T10:16:20.220Z
Answers.UserDisplayName: Michael Kay
Answers.Body: <p>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. <em>Never</em> 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 <em>good</em> thing; it helps the knowledge stick.</p>
  
  <p>There are two ways to read something like this, depending entirely on your familiarity with the subject matter.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p>The next day, read another chapter.</p>
  
  <p>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.</p>
  
  <p>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 <em>do</em> 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.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
  <p>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.</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T19:16:21.737Z
Answers.LastActivityDate: 2019-03-27T19:16:21.737Z
Answers.UserDisplayName: Nicol Bolas
Answers.Body: <p>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 <em>purpose</em> 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.</p>
  
  <p>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.</p>
  
  <p>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).</p>
  
  <p>Good luck!</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-29T15:00:56.087Z
Answers.Text: +1. And it makes a huge difference if the project is something I really want to make, as opposed to some homework I assigned myself because I wanted to add something to my resume. When I'm passionate about the end goal, the dry documentation suddenly becomes fascinating.
Answers.UserDisplayName: StackOverthrow
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-26T20:41:19.167Z
Answers.LastActivityDate: 2019-03-26T20:41:19.167Z
Answers.UserDisplayName: thesecretmaster
Answers.Body: <p>Man, I'm right there with you. I understand completely your situation, as I've been there myself many times.</p>
  
  <p>The key, I find, is not reading the tutorials. </p>
  
  <p>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.</p>
  
  <p>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). </p>
  
  <p>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.</p>
  
  <p>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).</p>
  
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T01:37:26.897Z
Answers.Text: This sounds like a really good idea, and something that is in line with my learning style. I do see one issue, however. That is that for Vulkan in particular there is a *lot* of background that is needed to do something even at a hello world level. I've seen posts that claim that you need over 1,000 lines of code to draw a triangle. This background makes an approach where I look for specific things less useful, as I won't know what specific things to look for.
Answers.UserDisplayName: john01dav
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T13:39:54.913Z
Answers.Text: @john01dav hmm, that *is* frustrating. I guess maybe you need to recalibrate what "hello world" looks like for vulkan, then? I don't know enough about Vulkan to be able to provide specific advice, but maybe you're doing something that doesn't draw anything on the screen, but sets something up in the background - anything, really (is there something in vulkan that acts as console.log or print for debugging?). It's just got to start small, so you can start seeing results quickly.
Answers.UserDisplayName: auden
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T21:32:51.367Z
Answers.Text: @john01dav these challenges are part of the reason why people build rendering/game/graphics engines on top of standards like Vulcan/OpenGL/DirectX. Its *hard* to understand and do all this stuff, and while knowledge is always useful, understanding exactly what goes into 1000 lines of boilerplate might have a lower payoff than something else.
Answers.UserDisplayName: mbrig
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-28T15:31:59.810Z
Answers.Text: @mbrig OpenGL takes nowhere near as much boilerplate, and can be easily encapsulated, it takes < 100 lines to draw a triangle with textures, I often find it easier to work in OpenGL than higherlevel engines, because now I not only need to know how what is going on with rendering, I have to understand this upper level API that restrict things (unless it is a framework that doesn't restrict access to rendering).
Answers.UserDisplayName: Krupip
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-28T15:37:31.800Z
Answers.Text: @heather  Vulkan requires a *looooooot* of other concepts orthogonal to rendering to even get started, you need to understand multi process synchronization and message passing (semaphores mutexes, event synchronization etc...), intermediate representation of a language (SPIR-V), memory management, in addition to everything you had to know about graphics for other APIs.  Swap chain management and synchronization, memory management with uniforms, images, and how to use commands properly are what really trip people up. This is required no matter the size of your project.
Answers.UserDisplayName: Krupip
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-29T12:07:09.300Z
Answers.Text: I might be going a bit off-topic with my comment, but where does PEP8 say camelCase (mixedCase) is not in style with the guide for Python?
Answers.UserDisplayName: lucasgcb
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-29T13:28:34.460Z
Answers.Text: @lucasgcb: See [this SO answer](https://stackoverflow.com/a/159745/6723642) with the relevant quotes from PEP8.
Answers.UserDisplayName: auden
Answers.ContentLicense: CC BY-SA 4.0
Answers.CreationDate: 2019-03-27T00:51:57.837Z
Answers.LastActivityDate: 2019-03-27T00:51:57.837Z
Answers.UserDisplayName: auden
Body: <p>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.</p>
  
  <p>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 <a href="https://vulkan-tutorial.com/" rel="noreferrer">written tutorials</a> that I get very distracted by almost anything. </p>
  
  <p>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. </p>
  
  <p>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.)</p>
  
  <p>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). </p>
  
  <p>When I attempted this for Vulkan, however, <a href="https://www.youtube.com/watch?v=wHt5wcxIPcE" rel="noreferrer">the only video tutorials that I could find</a> 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.</p>
  
  <p>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. </p>
  
  <p>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?</p>
  
Comments.ContentLicense: CC BY-SA 4.0
Comments.CreationDate: 2019-03-27T14:16:15.523Z
Comments.Text: These aren't exactly answers (hence, a comment), but here's some discussion about similar academic questions: (1) [How to stop hopping the learning chain and actually begin somewhere?](https://academia.stackexchange.com/q/89032/70557) (2) [How to read papers without falling into a rabbit hole?](https://academia.stackexchange.com/q/68605/70557)
Comments.UserDisplayName: BurnsBA
Tags: <self-learning>
Title: How can I get through very long and very dry, but also very useful technical documents when learning a new tool?
ThreadText: # How can I get through very long and very dry, but also very useful technical documents when learning a new tool?
  
  (Asked by: username_0 on 2019-03-26)
  
  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 username_3 periods, even if I put in significant effort. I find when I go through the [written tutorials](https://vulkan-tutorial.com/) 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](https://www.youtube.com/watch?v=wHt5wcxIPcE) 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?
  
  **Tags:** self-learning
  
  > **Comments:**
  > **username_1**: These aren't exactly answers (hence, a comment), but here's some discussion about similar academic questions: (1) [How to stop hopping the learning chain and actually begin somewhere?](https://academia.stackexchange.com/q/89032/70557) (2) [How to read papers without falling into a rabbit hole?](https://academia.stackexchange.com/q/68605/70557)  
  
  ---
  
  ## 11 answers
  
  ### Answer by username_12 on 2019-03-27. Score: 9 | Accepted answer
  
  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 by username_15 on 2019-03-27. Score: 28
  
  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).
  
  > **Comments:**
  > **username_0**: This sounds like a really good idea, and something that is in line with my learning style. I do see one issue, however. That is that for Vulkan in particular there is a *lot* of background that is needed to do something even at a hello world level. I've seen posts that claim that you need over 1,000 lines of code to draw a triangle. This background makes an approach where I look for specific things less useful, as I won't know what specific things to look for.  
  > **username_15**: @username_0 hmm, that *is* frustrating. I guess maybe you need to recalibrate what "hello world" looks like for vulkan, then? I don't know enough about Vulkan to be able to provide specific advice, but maybe you're doing something that doesn't draw anything on the screen, but sets something up in the background - anything, really (is there something in vulkan that acts as console.log or print for debugging?). It's just got to start small, so you can start seeing results quickly.  
  > **username_16**: @username_0 these challenges are part of the reason why people build rendering/game/graphics engines on top of standards like Vulcan/OpenGL/DirectX. Its *hard* to understand and do all this stuff, and while knowledge is always useful, understanding exactly what goes into 1000 lines of boilerplate might have a lower payoff than something else.  
  > **username_17**: @username_16 OpenGL takes nowhere near as much boilerplate, and can be easily encapsulated, it takes < 100 lines to draw a triangle with textures, I often find it easier to work in OpenGL than higherlevel engines, because now I not only need to know how what is going on with rendering, I have to understand this upper level API that restrict things (unless it is a framework that doesn't restrict access to rendering).  
  > **username_17**: @heather  Vulkan requires a *looooooot* of other concepts orthogonal to rendering to even get started, you need to understand multi process synchronization and message passing (semaphores mutexes, event synchronization etc...), intermediate representation of a language (SPIR-V), memory management, in addition to everything you had to know about graphics for other APIs.  Swap chain management and synchronization, memory management with uniforms, images, and how to use commands properly are what really trip people up. This is required no matter the size of your project.  
  > **username_18**: I might be going a bit off-topic with my comment, but where does PEP8 say camelCase (mixedCase) is not in style with the guide for Python?  
  > **username_15**: @username_18: See [this SO answer](https://stackoverflow.com/a/159745/6723642) with the relevant quotes from PEP8.  
  
  ---
  
  ### Answer by username_13 on 2019-03-26. Score: 11
  
  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 username_3 rabbit holes (although this still requires some willpower).
  
  Good luck!
  
  > **Comments:**
  > **username_14**: +1. And it makes a huge difference if the project is something I really want to make, as opposed to some homework I assigned myself because I wanted to add something to my resume. When I'm passionate about the end goal, the dry documentation suddenly becomes fascinating.  
  
  ---
  
  ### Answer by username_2 on 2019-03-28. Score: 6
  
  The answers by [heather](https://cseducators.stackexchange.com/a/5495/2068) and [username_13](https://cseducators.stackexchange.com/a/5494/2068) 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.
  
  > **Comments:**
  > **username_3**: As well as writing one's own documentation, as I work on a simple example that uses the tool/API I am trying to learn, I annotate (heavily) the code that indicates what component of the language I was using at that point in my code and WHY I was using it. Then test, test, test each bit of code as I add a little bit more.  
  
  ---
  
  ### Answer by username_9 on 2019-03-26. Score: 4
  
  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 by username_4 on 2019-03-28. Score: 3
  
  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.
  
  > **Comments:**
  > **username_5**: Welcome to [cseducators.se]! This answer seems to have good potential. could you perhaps expand it with slightly more concrete examples? Either way, I personally find this to be quite a good answer. I sure hope we'll see more content such as this answer from you again :)  
  > **username_4**: @username_5 Thank you, flattered :) I think the answer already explains my approach totally I'm not sure how can I expand it. But if you have a question or you think something is unclear, I can gladly include an answer for it. Thanks for your time.  
  
  ---
  
  ### Answer by username_6 on 2019-03-28. Score: 3
  
  > 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 by username_7 on 2019-03-27. Score: 3
  
  Almost all of my advice is from [Courseras "Learning how to learn"](https://www.coursera.org/learn/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](https://en.wikipedia.org/wiki/Kata_(programming)) 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 username_3 term memory.
  
  
  ---
  
  ### Answer by username_8 on 2019-03-27. Score: 3
  
  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 by username_10 on 2019-03-27. Score: 2
  
  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 username_3 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.
  
  > **Comments:**
  > **username_11**: The comment about tutorials is valid for many hastily-put-together articles found on the web, often written by someone who is no expert and wants to share what he/she has just learned. But there are also tutorials that are very carefully designed, crafted, and reviewed by experts. You need to be able to recognise the difference.  
  > **username_10**: @username_11, I've added an "exceptions notwithstanding". As a counterexample to your counterexample I'll mention a once de-facto Ruby-on-Rails tutorial, which was in fact a very username_3 and extremely well written e-book/website. Both didactically great; written in clean and well understandable tone. Exactly what you propose. The problem? It is for Rails 3. Rails 4+ are radically different. Most of the info in that tutorial is not only replaced by more modern stuff, but doesn't work anymore, outright. The problem? As it's so good, it still often turns up quite high in searches, and it is really...  
  > **username_10**: ... tempting and easy to fall into the trap of using/studying it; eventually getting ever more and more confused due to the fact that things mysteriously fail to work over time. But really worst of all; even the parts that still work follow an outdated mode of operation for several parts of that ecosystem. All in all, a developer following that as his main source at the beginning sets out with a (in part radically) wrong understanding, laying plenty of obstacles in the way.  
  > **username_11**: Yes, out-of-date information is always a problem on the web.  
  
  ---
  
  ### Answer by username_11 on 2019-03-27. Score: 1
  
  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.
  
  
  ---
  
  