Displaying content material as a graph: An exploration

Most net content material is designed to show with a strict hierarchy, tree-based or in any other case. What if it wasn’t?

What does it imply to show content material as a graph?

As a substitute of being displayed as a strict hierarchy, content material may very well be positioned in a number of classes inside a hierarchy, utilizing a polyhierarchy, or displayed as a sequence of interlinked nodes in a community—a graph.

Displaying content material as a graph may visually talk the relationships between concepts, duties, and matters in technical content material. A hierarchy additionally does this, however doesn’t all the time match the precise relationships between concepts and ideas in technical content material.

A graph may supply a extra versatile presentation, however content material is normally displayed hierarchically on the net. Why is that?

Why hierarchies are frequent

Hierarchies are frequent as a result of they match the standard means of explaining a brand new idea or matter — you begin out with an outline, briefly introducing a number of necessary issues and the way they match collectively, after which present further details about every factor afterward.

For instance, if I wish to educate you the way music is made, I’m not going to begin with an intense rationalization of how an instrument works to create sound. As a substitute, I’ll begin with a excessive stage dialogue in regards to the elements concerned in music: a tune, an instrument, scales, key signatures, tempo, after which transfer into extra advanced matters like methods to write music utilizing these elements.

• How one can make music
  • What’s a tune
    • What’s a hook
    • What’s a verse
    • What’s a refrain
    • What’s a bridge
  • What’s an instrument
    • Various kinds of devices
      • String devices
      • Woodwind devices
      • Brass devices
      • Percussion devices
    • How one can tune an instrument
  • What are the elements of music
    • Kinds of scales
    • Melody and concord
    • Tempo and time signatures
    • Key signatures
  • How one can write music
    • How one can write a hook
    • How one can write a verse
    • How one can write a refrain
    • How one can write a bridge
  • How an instrument works

It’s pretty straightforward to scan a listing of things and comply with the hierarchy that represents a logical development of data and data.

Hierarchies additionally mimic a standard means of displaying info—as a e-book, with chapters that symbolize hierarchies of content material.

Why use one thing completely different?

Hierarchies are frequent and acquainted. So why use one thing completely different?

Serve a number of psychological fashions

Presenting content material in a hierarchy supplies an implicit psychological mannequin to the reader. By ordering content material, there may be an implication that the knowledge is listed in keeping with its relative significance and within the order which it’s best to be taught the knowledge.

Within the case of the music instance, due to the hierarchy presentation, that signifies that it’s best to be taught the part components of a tune earlier than studying about devices, and earlier than studying about scales, key signatures, or tempo.

In the event you show content material as a graph, you may take away some ordering implied by a hierarchy:

By increasing a hierarchy, both by putting content material in multiple location, or by eradicating the ordering concerned in a hierarchy, you may serve a number of psychological fashions utilized by your readers and thereby enhance findability.

An article from Web page Laubheimer for Nielsen Norman Group^{, factors out some advantages of categorizing content material in multiple location:}

A polyhierarchical IA is a construction the place an merchandise exists in multiple place ­— that’s, it may be reached following a number of class paths.
…
Ideally, you wish to create classes that precisely describe your content material and merchandise, are extensible while you add new matters or merchandise, and match your customers’ mental models (which regularly differ from one particular person to a different).

And that could be a essential level — we frequently write documentation with an viewers in thoughts, however there may be all the time variation in familiarity and background.

For instance, as a result of I realized information evaluation with a language that performs aggregation with the statistical transformation command ^{, I’d search for the SQL perform GROUP BY alongside the COUNT() and SUM() perform reference.}

If content material may very well be displayed as a graph, depicting completely different relationships throughout classes and instructions, the content material can replicate many psychological fashions. The content material may grow to be the diagram.

Write higher documentation

A persistent problem for technical writers is to concentrate on writing user-centric documentation fairly than feature-focused documentation.

When you think about content material with the complexity of a person journey, with all of the requisite branches and forks, the constraints of linear hierarchies start to indicate.

It may very well be simpler to write down documentation in case you didn’t have to think about the place the content material belonged within the navigation or the desk of contents, however as an alternative thought-about the way it associated to different items of content material that already existed. We try this already, however should all the time create a hierarchy that considers order.

However typically order doesn’t matter. Generally order is completely different relying on the viewers. Hierarchies are rigid.

With out being constrained by a hierarchy, we may place documentation in a construction extra mindfully, answering questions like:

• What relationships do you wish to draw for the reader?
• When and the place may the reader encounter the duties described on this matter?

David Ryan at Pink Hat has tried this, mentioning in a tweet that:

Just a few of us used a graphing device at Pink Hat to indicate content material relationships, as we experimented with transferring away from “linear e-book” and tried to match content material with the person journeys.

For the music instance, we are able to acknowledge the truth that some readers may be accustomed to writing lyrics, however not accustomed to the idea of key signatures or scales. Different readers may be accustomed to songs, however can’t hold tempo simply, so wish to discover that content material in additional depth than others.

Enhance content material reuse

In the event you don’t have to attract strict hierarchies, it may very well be simpler to reuse content material. In case your content material is pocket-sized and particular to an idea or process, recontextualizing it might be so simple as including one other hyperlink to the graph.

In a hierarchy, to reuse content material you typically need to duplicate the content material to a different location—via single sourcing or in any other case—to make it logically related.

The flexibleness of a graph signifies that you should utilize labels or hyperlinks to attract connections throughout content material, fairly than duplicating it to a different location in a hierarchy.

Enhance machine legibility

Content material that’s not simply saved as a graph but in addition written for a graph could be much more legible to machines—the web site crawlers indexing content material to be used in search outcome rating algorithms and capturing datasets to coach machine studying fashions.

Most of that content material is already crawled as a graph, with the robots following hyperlink after hyperlink, indexing the web page contents in addition to the hyperlinks between them, constructing a graphical illustration of the online.

Writing with these relationships in thoughts may assist amplify the connections throughout content material, making these connections extra legible to the machines whereas exposing them to the human readers as nicely.

Relying on the way you put money into the standard of your data graph, the search advantages may create a aggressive moat in your documentation web site—offered the content material exists to help the search phrases.

Why don’t we show content material as a graph?

There are an a variety of benefits to displaying content material as a graph, however only a few web sites accomplish that. Why is that?

It’s troublesome to design

Web sites are based mostly on pages — and it’s troublesome to show the underlying construction to readers in a coherent means.

Having a navigation menu on the prime or the facet of a web page is an especially acquainted sample, in addition to “breadcrumbs” to assist folks keep an thought of the place they have been earlier than.

There are a couple of examples of content material graphs on the net already, they usually comply with some completely different patterns:

Andy Matuschak has created a type of a graph along with his Evergreen Notes ^{, which open hyperlinks subsequent to the content material that you just’re interacting with, and reduce alongside the way in which. Within the case of Evergreen Notes:}

there’s no index or navigational aids: you’ll must comply with a hyperlink to some start line.

It’s the same design to what Obsidian applied ^{. Obsidian additionally makes use of a graph and node-based structure to narrate native textual content recordsdata in your laptop with each other. It takes the graph visualization to the subsequent stage, however I really feel that graphs of this scale aren’t tremendous discoverable, regardless of being explorable, as a result of they’re so overwhelming. Obsidian additionally just lately launched tab stacks, one other progressive means of visualizing content material all of sudden.}

One other web site is the C2 wiki, which was described to me as “a dialogue web site that occurred to be formed like a reference information.” It primarily creates a map for you as you navigate via it, with the hyperlinks you open floating subsequent to the origin.

I really like this design as a means of protecting observe of a particular journey via the content material, enabling the reader to construct their very own workflow out of the content material, but it surely raises a problem relating to sharing hyperlinks.

Within the screenshot above, my pathway ended on the DepthFirst web page, however in case you open that hyperlink, you see solely the web page—not one of the journey that led me there, and not one of the nodes within the graph that you just may wish to discover alongside it are seen—just a few hyperlinks within the web page itself.

These two websites expose the principle design challenges:

• What do you show on the touchdown web page, or entry level, right into a web site like this? Most readers encounter documentation from search, however many nonetheless browse to the positioning itself—particularly potential prospects or workers trying on the firm web site.
• How do you make the graph seen when viewing a discrete web page (or node) within the graph? How do you make the context of the present web page seen to the reader?

The touchdown web page choice may be to do one thing much like many hierarchical documentation websites—show a search bar and a few key “entry level” nodes with choose department or dependent nodes displayed.

Making the graph seen may very well be an fascinating design problem, relying on what you select to do:

• Ignore the graph and present solely the node, leaving the hyperlinks as the one technique to navigate to different nodes (and comply with present net searching patterns with out including new ones).

• Protect a particular journey when sharing a hyperlink to a particular web page, and supply a “historic” graph view, much like what Andy’s Notes does.

• Present a zoomed-out view choice, the place you might reduce a web page and examine the close by graph nodes:

  

  

• One thing else fully!

It’s complicated for readers

Hierarchical content material is a dominant net format, and consequently, it’s acquainted. Acquainted design and structure patterns are simpler to navigate since you don’t need to be taught something about methods to use the positioning, you may simply navigate utilizing the patterns you’ve already realized — scan the navigation bar, scan the desk of contents, and skim the headers on the web page or use ctrl+f to seek for a key phrase within the textual content.

As Mark Baker factors out in Every Page is Page One, individuals are info foragers. The readability of a graph and the sheer quantity of content material which may exist in a single may not lend itself nicely to the scanning-first habits that we’ve advanced as net readers.

As a substitute, in case you show content material as a graph, readers are confronted with an unfamiliar sample that might require them to be taught new buttons and interactions with the intention to discover what they want. That’s a hindrance to readers of technical documentation, as a result of their aim is to reply a particular query, full a particular process, or find out about one thing — not learn the way your web site works.

As well as, displaying content material as a graph lacks a transparent hierarchy, which causes one other huge downside: there’s no clear start line.

As Kelley Gordon factors out in her article for Nielsen Norman Group, Visual Hierarchy in UX: Definition:

In the event you wrestle to seek out concentrate on a display, it’s probably that the structure is lacking a transparent visible hierarchy.

The web page’s visible hierarchy controls the supply of data from the system to the top person — it lets customers know the place to focus their consideration.

Arriving at a webpage with out visible hierarchy and solely a graph with nodes will be disorienting for readers.

Most readers would then use one other type of exploration, reminiscent of search, to seek out what they’re searching for.

As a result of a graph lacks a transparent visible hierarchy and will be overwhelming, the designs of Evergreen Notes or the C2 Wiki make sense as a result of they reveal the graph as a journey as you navigate the web page. Different websites that use graphs don’t normally make them seen as you navigate.

One exception is the basic web site HyperPhysics Concepts^{, which makes use of a visible graph illustration with clickable hyperlinks with the intention to show you how to navigate the positioning:}

This graph is a hierarchical and ordered graph, however much less hierarchical than a standard desk of contents, and made seen to the reader. Every node of that graph is clickable, opening a brand new web page with content material, or typically a brand new graph:

The Hyperphysics web site makes the graph seen however not on the expense of the content material. The graph will be annotated and function one other type to speak the relationships between the ideas described within the content material.

One other exception is the positioning Every Noise at Once. The data sources for it are sadly now defunct, however the web site itself shows not a graph, however a group of genres laid out as if there have been node connections seen.

It’s the thought of a graph, however with no true connections. The location itself refers to it as a scatter plot — so there are imprecise associations, however no true hyperlinks. In the event you go deeper into the graph and choose a style, you see the same scatter plot of the artists in that style:

Websites with hierarchies additionally use breadcrumbs as a technique to present you the place you’re within the total web site map. Content material that you just work together with purely in graph type would as an alternative must both assemble dynamic breadcrumbs based mostly on the trail via the content material that you just took, or take a distinct strategy fully, like counting on class tags.

Each Noise at As soon as, with the versatile graph-like exploration format, maintains a breadcrumb that successfully exhibits the nodes surrounding the one that you just’re at the moment visiting:

Finally, there are a number of choices for displaying content material visibly in a graph, however most of them both retain a hierarchy to help readers in scanning and foraging for info, or haven’t any visible hierarchy and drive the reader to discover, use search, or quit within the face of overwhelming choices.

It’s too versatile

Content material graphs aren’t a brand new idea. Displaying content material as a graph may be hardly ever achieved, however storing content material as a graph is a standard follow—normally known as a data graph.

As Sarah O’Keefe discusses for Scriptorium, there’s a cost to knowledge graphs. A type of is the problem to writers:

We now have to consider the assorted content material or information objects, perceive how they relate to one another on the data graph stage, after which deliver them collectively right into a coherent expertise, whether or not a webpage, a doc, or one thing else fully.

That’s quite a bit to think about. Writers utilizing DITA (Darwin Data Typing Structure) and XML-based structured authoring options may already be accustomed to these challenges, and the chunking strategy to scale back content material to its related bits which then have to be reconstituted right into a coherent expertise on a webpage.

I haven’t labored in a DITA atmosphere earlier than, and most of my expertise is with instruments that don’t use a database to retailer content material, not to mention a graph database. Many docs-as-code instruments require a hierarchy of kinds to dynamically generate a desk of contents (Sphinx is one instance) or to supply some sense of order to the flat file construction of a repository.

In relation to organizing content material, it may very well be releasing to think about all of the other ways a subject may very well be related to a reader, but it surely may additionally find yourself exhausting, deciding the place to attract the road.

For the music instance from earlier, a web page, or graph node, about “How one can write songs” may very well be linked to:

• How one can write a bridge
• How one can write a refrain
• How one can write a verse
• How one can write a melody
• How one can write a topline
• How one can write a hook
• methods to write lyrics
• methods to write a concord
• methods to use a digital audio workstation (DAW)
• and extra…

Nevertheless, the flexibleness of a graph may add chaos. If this content material may very well be linked to different content material, what ought to it’s linked to? What different nodes are related? A graph may shortly flip right into a sea of potentialities, fairly than intentional selections about relevance.

At a sure level, the try to keep away from lacking a related hyperlink, or to attempt to make your content material as discoverable as attainable via a data graph, would dilute the specific psychological fashions and diagramming potential attainable with a graphical presentation of content material.

As a substitute of replicating some psychological fashions, the graph may as an alternative begin to symbolize all attainable permutations of a psychological mannequin, and cease representing something of worth in any respect.

However the act of contemplating all of the completely different places the place your content material may be related, what different entry factors may exist, may lead to extra considerate documentation content material. You’ll be able to think about it as a part of a complete system. By contemplating the content material as a part of a graph, you may extra simply deal with the content material as a part of an expansive floor, fairly than a discrete aspect on a particularly ordered checklist.

In contrast, as a result of a hierarchy is strict, it forces selection. If this content material needed to exist in a single place, the place is the most related place?

That one selection will be daunting, particularly when selecting what the highest of the hierarchy ought to be.

In a dialogue within the Write the Docs Slack neighborhood, Wouter Veeken factors out that one problem with hierarchies is deciding what to place on the prime of it, asking if anybody has a “basic technique for deciding which attribute ought to be the highest stage of the tree?”

Therein lies the tradeoff. For some content material, selecting a location in a hierarchy is an arbitrary selection. For different varieties of content material, it reifies a related order to a process.

For instance, if you wish to write a tune, you can begin with a melody, a concord, or lyrics. To put in writing lyrics you can begin with a refrain, or a verse, or a bridge. None of these have an order. However if you wish to produce a tune, a tune have to be written first. In that case, order issues.

It is a key benefit of getting a graph construction—every thing is a set of relationships, there is no such thing as a designated “prime” of the tree to establish. You could possibly even select to show highly-related matters in a different way than others, and use the knowledge offered by the graph construction itself to find out what content material is most beneficial.

It’s troublesome to write down chunked content material

These are the challenges with structuring the content material, however there are additionally challenges with writing the content material.

Carrie Hane points out in a discussion about Knowledge Graphs on Sarah O’Keefe’s LinkedIn that:

adoption of structured, decoupled content material continues to be wanted to undertake data graphs. And that could be a large leap.

I agree with that utterly. Every bit of content material within the C2 wiki or the Hyperphysics web site was a discrete part of content material — a definition of an idea, for instance. That kind of chunked content material matches nicely inside a data graph.

Technical content material written for a hierarchy, or with an implied order, can typically find yourself fairly lengthy and detailed — maybe with one web page describing every thing it’s essential learn about one thing. To proceed the music instance, you may find yourself with a web page like:

• How one can write a tune
  • About tune elements
  • Write lyrics
    • Write a verse
    • Write a refrain
    • Write a bridge
  • Write a melody
  • Write a concord
  • Write a bassline
  • Write a percussion observe

That web page is stuffed with task-based content material that may very well be simply separated into completely different graph nodes, but it surely may also embrace definition content material blended in, like:

• What’s a hook
• What’s a topline
• What’s a key signature
• What’s tempo

That definitional content material would additionally get damaged out into particular chunks. Impulsively, as an alternative of writing an end-to-end matter all about songwriting, you’re writing tiny chunks of content material which may not be as fascinating, compelling, or cohesive to write down or learn.

Sparse content material and dense content material don’t scale in a graph

Graphs are solely helpful if there are many connections. A graph with just a few nodes doesn’t talk a lot as a diagram of a psychological mannequin:

However, too many nodes is impractical and in addition doesn’t talk a lot as a diagram of a psychological mannequin:

Seen graphs: The way forward for displaying content material?

Finally, it’s unlikely that seen graphs would grow to be a normal follow for displaying technical content material. It’s a fancy design and rendering downside, and whereas there’s an opportunity that the novelty may get somebody to click on round in a graph for a bit, somebody with a particular query in thoughts desires to have the ability to scan for info.

A hindrance to scanning is quantity of content material. Given the quantity of content material on many documentation websites, and that individuals are accustomed to navigating in digital gadgets, most individuals default to using search as their first choice for navigation.

If everyone seems to be utilizing search to navigate, displaying content material as a graph wouldn’t make a lot sense.

As a substitute, implementing a data graph because the background construction for a documentation web site, with clear steering about methods to join the nodes of the graph, has the potential to enhance search outcomes for readers and permit versatile categorization for writers.

A data graph lets you’ve got the most effective of each worlds. As Manav Modi from ProductX factors out in How is Airbnb optimising Search and Discovery using Knowledge Graphs? 🎯:

The graph may also be hierarchical, with high-level ideas branching right down to extra particular particulars, permitting for a streamlined information group.

An alternate that may protect the graph conceptually however not visually is the tile-based strategy frequent on many documentation touchdown pages, with type and filter choices:

• One compelling instance is the Redis command docs, as shared by @matheusfelipeog of their lovely docs repository.
• One other one is the GitHub Docs which mixes a tile-based presentation with a table-of-contents hierarchy, in addition to really useful pages based mostly on “getting began” or “fashionable matters”.
• The Digital Ocean docs additionally use a tile-based strategy mixed with a desk of contents.
• Mode uses tags on their resources page, letting you filter by kind of content material and/or the topic of the sources.

In these fashions, the graph isn’t made obvious, however the node relationships nonetheless exist via tags or content material sorts and will be explored with out utilizing a desk of contents. This strategy allows you to achieve some advantages of visually displaying content material as a graph with out essentially the most troubling challenges—an unfamiliar and difficult searching expertise for readers.

Irrespective of the way you visually current your content material, the act of putting content material inside an info structure and structuring it’s precious and reifies a psychological mannequin for the readers and the writers.

It’s impractical to make a graph seen to readers, however I nonetheless suppose it might be cool.