My first time through Angular framework’s documentation section had focused on “Getting started” and “Tutorial” sections, just to get a toehold on things. Due to a firehose of information about this large framework, I didn’t retain very much. Now I’m taking a second pass through documentation, armed with more knowledge and experience to understand more of it. I drew up a tentative plan earlier, but I’ve already decided to deviate from that plan. After I read through the StackBlitz tutorial, but before I started hands-on with “Tour of Heroes” tutorial again, I decided to read the documentation section “Understanding Angular” whose overview page started with this:

To understand the capabilities of the Angular framework, you need to learn about the following:

• Components
• Templates
• Directives
• Dependency injection
  The topics in this section explain these features and concepts, and how you can use them.

I admire this goal, but the reality was I lacked prerequisite knowledge to understand all of it. This is fine! Every time I understand a little more. At a rough guess, I would say I understood and retained about 5% of this information after my first effort, and this second effort had roughly 30% retention.

Live Code Everywhere

The length and quality of documents in this section vary greatly, probably reflecting different authors contributing from their own perspectives. But at the end of the day, developers want to see code and we have them. Most (all?) of the topics included links to sample code in both live-running form (running on StackBlitz) as well as downloadable source code example. Some go much further, for example “component interaction” goes as far as including test code. And in several cases, sample code covered concepts that were not covered on written pages, so it’s always worth checking out that link.

Nonlinear Organization

Sometimes my confusion is not from missing prerequisite knowledge, but counterintuitive organization of information. For example: Under the binding section, Property binding is the next-to-last item on the list yet it is listed as prerequisite by the second (attribute binding) and third (class and style binding) documents. To make sense of everything I have to jump around this page.

Attributes vs. Properties

Several documents in the binding section emphasized that we bind to properties and not attributes. But they didn’t explain what that difference meant! Looking outside this site, I found this StackOverflow thread which included a gem of an explanation: “When writing HTML source code, you can define attributes on your HTML elements. Then, once the browser parses your code, a corresponding DOM node will be created. This node is an object, and therefore it has properties.“

Angular Directive Long Form

As an Angular beginner I can see Angular directives as a very powerful mechanism, but the syntax can be tough for me to decipher. Eventually I learned this was because we frequently see shorthands for using directives, and the structure is easier to comprehend when we see the “long form”. This snippet was shown as a *ngFor “long form”, and it was quite illuminating!

<div *ngFor="let product of products">
  <h3>
    <a [title]="product.name + ' details'">
      {{ product.name }}
    </a>
  </h3>
</div>

It was not as concise as the shorthand, but much easier for me to decipher what’s going on. Compare the above to another example of ngFor directive:

<ul>
  <ng-template ngFor let-hero [ngForOf]="heroes">
    <li>{{hero.name}}
  </ng-template>
</ul>

(Note that these are two different examples of ngFor and they do different things, because I copy/pasted them from different sections of Angular documentation. I’m only using them to compare syntax.)

Ready for Round 2

After reading through “Understanding Angular” I can’t say I totally understand Angular yet, but I have a much better understand of how it goes about its business. I expect some of this information to be reinforced as I go through their “Tour of Heroes” tutorial again, because I think I’ll recognize them the next time around and have a better idea of their usage context.