SEOArchive edition6 min read

Internal linking for a technical knowledge library

Create relationships that help visitors move from a concept to a practical next step.

A network of connected nodes and branching routes — Internal linking for a technical knowledge library
Original ARTware computational illustration.

A technical library works best as a collection of documents with known relationships. An isolated article can be accurate and well written, yet a reader may not know where to turn when it exposes a second problem. Suppose a developer reads about canonical URLs and realizes that an upcoming navigation change affects existing routes. The natural next document is a guide to preserving and testing those addresses. A generic link to the journal home is less informative, even if it makes all the articles technically reachable. Internal linking should account for the steps a person might take as they move from a general explanation to a decision and finally to implementation.

Draw a small picture of the collection

Before editing anchors, assemble a list of published articles and their primary purposes. A web engineering library might contain a general page about site performance, a guide to image formats, an explanation of rendering, a piece about script-free content, and a checklist for releases. Identify relationships between them. The rendering article explains a cause of the symptoms described in the performance overview. The image guide handles one class of asset, while release testing applies to a change that has already been developed. This makes a better basis for linking than deciding that every article containing the phrase web performance should link to the same destination.

A category page remains useful as the main entrance into one part of the collection. Give it readable summaries and ordinary links, arranged in an order that makes sense for its readers. It is possible to have several types of entrance: a journal with recent articles, a collection organized by subject, and a guide that introduces alternatives and points towards specialist discussions. These are not interchangeable. Dates support discovery of recent work, the category shows breadth, and the introductory guide supplies context for somebody unfamiliar with the subject. An archive organized exclusively by publication date is unlikely to help readers discover an old article answering their current question.

A useful link belongs where its destination starts to matter. In an article about replacing a site template, a paragraph may mention that image compression has little effect if the initial document is delayed. At that point, a link to an explanation of initial request timing can expand on the distinction. At the end of the article, a link to the release testing guide might be appropriate because the reader now has a change to verify. Putting both links in a random paragraph near the opening makes their purpose harder to see. The reader should be able to decide whether to follow a link without inspecting a separate list of search terms.

Choose a phrase that matches the subject of the destination. 'Check old and new routes' says more than 'learn more here' when it points to a migration test. The exact article title may be too long to fit naturally inside the original sentence. In that case use the narrower phrase that describes why the reader would want the target page. Avoid changing an existing technical term into an anchor on every appearance. Repeating a link adds visual noise and may imply several distinct destinations when all the links resolve to one. One well placed connection is often enough to establish the relationship within an article.

Related reading: Designing a small internal knowledge system.

A related reading section can support exploration by recommending a few substantially different pieces. Imagine a guide about application data models. A reference to module responsibilities helps the reader consider which component should own an operation. A guide to software interfaces helps with the contract exposed to consumers. A testing guide describes how the chosen behavior might be verified. Three articles with almost the same introduction to data modeling provide a less useful selection. Pick recommendations using the reading task and the content of the destination rather than an automated check for shared words unless the automated system is constrained by explicit relationships.

A small site with dozens of articles does not require a complicated recommendation algorithm. Editors can keep a field containing a few related article identifiers in the publishing record. Stable identifiers preserve the association even if a heading changes. When the site generates a page, it looks up the current preferred title and address for each identifier. This reduces the maintenance cost of copying full links into a footer. It also permits validation: the build can report a recommendation that points to an unpublished record, points back to itself or repeats another recommendation. The editor still owns the decision about why the documents belong together.

Layered flowing curves with fine network-like intersections
ARTware visual study. A complementary computational composition.

Identify weak and isolated destinations

Create a small inventory of incoming links for all published URLs. Count where each link appears rather than treating every occurrence identically. A route present in global navigation appears many times but may have little contextual relationship with any page. A specialist article mentioned from two directly relevant guides can be much better integrated than one linked from thirty unrelated footer lists. Look for articles reachable only from the journal index, those without a category link, and those reachable only after following long sequences of old links. Each isolated page is an opportunity to consider whether it lacks a meaningful relationship or no longer fits the editorial collection.

This check can be implemented with a crawler over the final HTML. Parse relative links against the current page address, strip fragment identifiers when counting distinct destinations and exclude references that do not lead to local documents. Resolve any redirects before deciding which links are incoming to a page. Store both the source URL and final destination so that individual failures can be corrected. The resulting list is not a quality score. Its purpose is to identify broken links and unexpected gaps. Inspect some of the reported source pages by hand to distinguish actual recommendations from sitewide navigation and repeated links inside a template.

A knowledge library changes as articles are expanded or combined. If an older overview is merged into a newer and genuinely equivalent guide, update the article relationships to identify the surviving record. If a route changes, make sure the generated category pages, breadcrumbs and related reading blocks produce the final address instead of relying on the redirect to repair every visit. Redirection is valuable for older incoming references that are outside the publisher's control. It is not an excuse to leave an internal route inventory stale. Check links in rich article text separately from generated ones since editors may have entered an address directly rather than selecting a publication record.

Check how a reader moves through the site

Run a few simple navigation exercises. Start with an article about site migration. Use a contextual link to learn about duplicate addresses, then reach an article about release verification. Determine whether you can return to the relevant collection and find a distinct article concerning metadata. The exercise should work on a relatively narrow screen as well as a desktop. Test links with ordinary keyboard navigation; a list of article titles hidden inside an elaborate graphical component is insufficient if a visitor cannot activate it reliably. Check the result with scripts disabled as well, if the library is intended to expose ordinary documents directly.

As the collection grows, keep the editorial records and the link inventory in the same maintenance routine. Whenever an article is published, check that the topic index includes it and that at least one truly related document points towards it. Whenever a page is retired, inspect the sources that currently link to it. This changes internal linking from an occasional cleanup into an ordinary publishing decision. The library can gain considerable depth while still presenting a manageable set of next steps to a visitor arriving at any individual article.

Explore the implementation area: Technical SEO.