Technical Writing Guide: Adding Links
TLDR: If something is important, link it!
Congratulations 🎉
If you’re reading this, you probably want to improve your technical writing skills.
Background:
I’m a Data Engineer with 6+ years experience. I’m also an editor for the Data Engineering Things publication.
I review a lot of technical articles and thought I’d share some techniques to improve technical writing.
TLDR: Checklist of what to link
Generally, your technical discussion should have links for the following:
- Programming Languages*
- Frameworks / Libraries
- Important concepts
- Books
- Funny stories or well known incidents
- Clever things you choose to emphasize
* only if they are central to your technical discussion
1. Link Important Frameworks or programming languages
When writing an article about an important framework or programming language, provide a link on the first mention
It might sound obvious, but it gives readers a starting point for learning more. It also helps emphasize importance + demonstrate credibility.
Example: Mentioning a framework
You can run dbt-core locally, without need to deploy to the cloud.
Don’t go overboard: Only link what’s important
Not every language, library or framework needs to be linked.
Example: Going overboard
DBT tasks have to be SQL files, or Python files that don’t do arbitrary things.
💡 This is too much…
2. Link important concepts:
When mentioning an important concept — one which is central to the technical discussion, consider linking to a canonical source.
Benefits:
- Emphasize importance
- Keep narrative flowing without needing to explain things
- Demonstrate credibility
Suitable Canonical Sources:
- Wikipedia article
- Well known blog post
- Digital textbook
- Documentation
Example: Canonical source missing
DBT executes a directed acyclic graph (“DAG”) for all data models.
Since a DAG is a very important concept, central to the technical discussion, consider linking to something canonical like https://en.wikipedia.org/wiki/Directed_acyclic_graph
Here’s what that now looks like:
DBT executes a directed acyclic graph (“DAG”) for all data models.
Even if people don’t open the link, they now know that it is an important + canonical subject.
Q: What if there are no Canonical Sources?
There are times when there are no canonical sources about a technical subject — only random blog posts. What do you do there?
Congrats! 🎉 You are a pioneer. People are looking to you for/as a canonical source. Choose anything you’ve found helpful or particularly relevant.
Example: Choose your own canonical source
Context switching in technical discussions are hard – media as context switches are a clever solution here.
This is an excerpt from an article I’ve written. 😄
3. Link loaded statements
Don’t leave people hanging.
Highly implicit statement (such as loaded statements, inside jokes, or “well known stories”) may be jarring for readers of different cultural backgrounds.
Example: Loaded Statement
A.I. dazzles, but should never be trusted to produce reliable and factually correct results unless the parameters are strictly laid out by people using it before it is set in motion. [source: NYT Opinion]
The author here is referencing the danger of unregulated AI. It is implied that only a few companies are participating in the creation of large public-facing AI projects. Instead of explaining all the complex relationships and implications, I’ve chosen to link that loaded statement to a highly regarded article about the challenges and impact of AI regulation.
Example: An Inside Joke
Network faults happen all the time, caused by earthquakes, solar activity, or even shark attacks.
Instead of leaving the shark attacks as an inside joke, I’ve linked it to its source.
I didn’t link the mention of other causes of network faults, since they are well known (and they are not essential to my technical discussion). The shark attacks are funny and I am choosing to emphasize that.
Example: Well known Cultural Reference
It’s as though Icarus were telling the world, “Don’t forget to wear plenty of sunscreen.” [source: NYT Opinion]
Not everyone is familiar with the story of Icarus (the boy who flew too close to the sun). I’ve therefore linked the reference to a well written article about Icarus’ story.
4. Link references / books
This one is obvious. If you mention a book, or author, link it!
This goes the same for images of (or from) books.
Example: Referencing an author
Xinran writes really well.
You may not know who Xinran is (founder of DET) — so I linked her name.
Summary:
Links / references are an important tool for demonstrating what is important. Links as pointers towards further resources help your readers continue their learning — as well as lending your voice more credibility. Lastly, don’t leave people hanging!
Technical Writing Guide Series:
This article is part of a series on technical writing best practices.
- Emphasizing Personal Experiences with Callouts
Draw attention to your personal experience without disrupting the flow of your narrative - Technical Writing Guide: Compelling Titles and Subtitles
Draw people in with a well crafted title. Focus their attention with a good subtitle.
