In addition to writing code, developing software involves a lot of reading. There are many forms of reading involved, including familiarizing oneself with new systems (or technologies), evaluating alternatives, reading documentation, and troubleshooting issues.
Consider a developer learning a new JavaScript library. The process would likely include:
Reading the installation instructions.
Understanding configuration options.
Reviewing API documentation.
Studying example implementations.
Investigating common errors.
Comparing alternative approaches.
Each of these resources typically includes at least a little bit of information that will eventually be very useful. The difficulty lies in remembering exactly where that information came from.
While a bookmark can direct the user back to the correct site, it does not indicate which paragraph explains a particular configuration option or which portion of the documentation describes an error condition.
This is where digital highlighting comes in. By highlighting the most important parts of a document, users can quickly identify where the key information resides.
Bookmarking vs. Highlighting
Bookmarks are useful for saving whole sites. However, bookmarks alone do not enable you to recall a specific piece of information buried within an extended article.
To illustrate this, assume that a programmer saves a 4000 word tutorial on “asynchronous” JavaScript, because there is a single great explanation of Promise.all().
Later, the programmer returns to the saved page, but still must find the relevant section. Now picture if the programmer had identified the explanation in question while initially reading it. This would represent a much smaller distinction, but one with greater implications. The programmer now has a visual cue referencing the information that was most critical.
Bookmarks and highlights accomplish two distinct things:
Tool
Primary purpose
Browser bookmarks
Save web pages for later
Digital highlights
Point out important passages
Notes applications
Organize ideas & create personal explanations
Documentation
Serve as authoritative technical references
Tools like bookmarks and highlights are complementary; they don’t compete with each other.
Highlighting Technical Documentation
Much of the technical documentation that developers read is information that they will likely refer to multiple times over the course of a project.
For example, when learning about JavaScript array methods, a developer may come across descriptions of map(), filter(), and reduce().
One technique for organizing reading is to develop reading sessions based upon specific learning goals. In the case of learning about front-end frameworks, you could establish three separate reading sessions:
Components: Identify how components are structured and reused throughout an application.
State management: Determine how state is created, changed, and shared among components.
Routing: Document how routes are configured and navigated throughout an application.
Performance: Identify areas of potential performance improvement related to rendering and optimization.
Deployment: Document all aspects of deploying your application including how to perform builds and deploy to production environments.
Using this methodology you take disparate reading sessions and transform them into an organized learning experience. Additionally, this methodology is beneficial when changing between frameworks as well, since you can easily determine which concepts are comparable and which are unique to that particular framework ecosystem.
Using Highlighting While Debugging
Debugging is another area where highlighting plays an essential role. Debugging often requires going back and forth between an error message, documentation, discussions online, and examples of code.
For instance, suppose an application throws an error when attempting to handle an asynchronous request. A developer may find several useful articles online:
Discussion on rejected promises.
Documentation on handling errors.
Article discussing ‘async’ and ‘await’.
Tutorial demonstrating using a certain API.
Instead of saving all the documents without any reference to context, use digital highlighting to identify the specific paragraphs that address the issue. You can also add a brief note on why you chose to highlight that paragraph. For example:
“Good explanation of what happens to promises after being rejected”.
When dealing with a similar issue in the future, you’ll have a better place to start your search for answers.
A Practical Example of Highlighting During Research
Assume you’re doing some research into how JavaScript’s .filter() method operates. You’ve found a good explanation of how .filter() generates a new array populated with items that pass a given test.
You could choose to highlight both the description of .filter() and the example illustrating usage of .filter():
javascript
let numbers = [1,2,3,4,5,6];
let evenNumbers = numbers.filter(function(number) {
return number % 2 === 0;
});
console.log(evenNumbers); // [2, 4, 6]
The significant details here are:
.filter() calls a function for every item in an array.
Each function call determines if the current item should be added to the resulting array.
.filter() creates a brand-new array with all items that were passed by the functions called by .filter().
The array being filtered remains unchanged.
A developer studying array methods may wish to revisit these key points while working on a project. Highlighting the relevant passage makes locating it significantly simpler than having to go through the entire tutorial once again.
The same approach applies to unfamiliar methods, framework configurations, command line options and debugging procedures.
Using Highlights and Personal Notes Together
Highlighting is used to capture relevant information from an external source. Note-taking enables you to encapsulate what you learned from that source.
They each serve unique purposes:
Relevant excerpts from original documents are captured via highlighting.
Relevant excerpts from original documents are encapsulated via note-taking.
Example:
A developer studies closures in JavaScript. The developer highlights sections explaining how an inner function maintains references to variables defined outside itself, even after execution terminates for the outer function. The developer takes a personal note stating:
“Closures allow a function to retain access to variables declared in the space where it was originally defined even after the outer function completes execution.”
The benefit of combining highlighting with note-taking is twofold:
Original material captures relevant information from source materials.
Personal notes capture the developers own interpretation of that information.
Personal notes for developers may also include:
Project where concept applies
Error demonstrated by concept
Related API or programming concept
Question still unresolved
Combining both types of documentation makes the process more meaningful than if only one type were used independently.
Maintaining Trustworthy Sources
In addition to creating meaningful connections between external and internal knowledge sources, maintaining trustworthiness in external information is equally as important. Simply because content is presented in an article doesn’t necessarily mean it is accurate or applicable.
Therefore it is recommended to evaluate the credibility of external information before applying it in practice. Consider the following factors when evaluating credible sources:
Official documentation?
Does the article discuss the current version?
Was an example provided?
Did the article mention important limitations?
Could behavior be replicated?
Do other reliable sources support the author's explanation?
Trustworthiness matters because software development technologies evolve rapidly. Articles written months or years ago may describe obsolete versions of an API or configuration option. Therefore it is important to keep track of original sources and check for updates periodically.
Developing a Consistent Approach to Technical Research
A recurring theme throughout this book has been that technology evolves rapidly and it follows logically that developers need to continually update their skills accordingly. Establishing routines and processes that encourage repetition is key. A consistent research routine reduces wasted effort when searching for previously uncovered information. Below is an example of a simple process for establishing consistent research routines:
Step 1: Identify Problem
Know what you’re trying to learn or solve before beginning your research.
Step 2: Locate Credible Sources
Start your research with official documentation whenever possible.
Step 3: Understand Content Before Selecting Text to Highlight
Do not select text until you have fully grasped the surrounding explanation.
Step 4: Highlight Important Sections of Content
Focus on definitions, examples, limitations & useful instructions when highlighting content.
Step 5: Provide Context for Your Own Understanding
Create a brief note explaining why you needed to recall that section of content at a future time.
Step 6: Validate Technical Details
Test examples and compare them with current documentation.
Step 7: Review Past Research
Review relevant material whenever working on similar projects or tasks.
This process is simple enough to be used consistently without transforming research into unnecessary paperwork or overhead.
Conclusion
Improving the way developers consume technical information can positively affect productivity as much as improving their coding efficiency.
Digital highlighting offers developers a practical means of identifying key pieces of information contained within documentation, tutorials, articles and online forums.
Used in conjunction with bookmarks, personal notes and validation of sources, digital highlighting can assist developers in structuring their learning and solving problems more effectively.For more details visit Awesomehighlighter.com
Top comments (0)