This page is an informal press kit for the “Linking Manifesto” i.e., the Manifesto for Ubiquitous Linking, as a FAQ, by its editor Luc P. Beaudoin. It is not part of the official manifesto.

When will the manifesto launch

Dec 6 2021 00:01 EST.

Where is the manifesto ?

Like the Agile Manifesto, the Manifesto for Ubiquitous Linking is on its own website.

What’s the password of the manifesto site?

Until the publication date, it is the same as this web page. Then the password will be removed and the Manifesto will forever be publicly available.

What is this about in a nutshell?

Many software developers (large and small) make it surprisingly difficult to directly re-access information , with adequate non-tracking links, in their software. Those behind the Manifesto for Ubiquitous Linking are hoping to change that.

Why does this matter?

Everyday and professional researchers may be devoting more time to their online searches than they actually need to—thanks to the approaches taken by software companies that have the ability to provide clean hyperlinks, but who rather fuse tracking and other diverting tactics. Not only does this interfere with users’ psychological flow but it tires them and wastes their time. A group of over 23 (and counting) academics, developers and writers are now calling on software developers to rethink their approach to linking content. To redress this situation, they are jointly publishing (on Dec.6) the Manifesto for Ubiquitous Linking.

There’s more to it than that. Some of which is explained below.

Who are the original signatories (“originators”) of this manifesto?

The originators are listed here: Originators – Linking Manifesto. They are software developers, professors and podcasters who believe persistent information served by software should be “linkable”.

What does it mean for information to be linkable?

In a nutshell, it means that information resources should have a name and address (a URL or identifier) that can be conveniently obtained, from the software that presents them, through a user interface and automation. An automation interface is known as an “application programming interface (see Wikipedia).

Please note: many apps will present you with a document, let’s call it “Foo”, containing many links. They allow you to control-click on links in Foo, and will present you with a Copy Link menu item to the destination of each link. And yet might not provide a Copy Link for “Foo” document itself. That is a major part of the problem .

What information should be linkable?

We believe almost all persistent information resources that a user can re-access through a software program should be linkable via that software or its host environment (such as a web browser).

People are accustomed to copying URLs or entire links (URL & name) in web browsers. But not all information in web browsers that should be linkable is linkable! For example, when you click on an email’s label in iCloud.com, iCloud.com loads the content of that email in the browser. However, the address of the resource in the web browser address bar does not change, nor does the name of the tab! Here’s the URL when you access an email in icloud.com: iCloud Mail: https://www.icloud.com/mail/. And another email: iCloud Mail: https://www.icloud.com/mail/. The title and the address (URL) are the same. That’s useless for referencing!

We maintain that not only should web resources be linkable, so should resources in software that is stored on the Mac (whether synced or not with a cloud storage service). Fortunately, many applications already provide this. See Linkable Mac Applications for a subset of Mac apps that provide automation for getting links (some of them also provide a UI). For example, Tinderbox, OmniFocus, EagleFiler, and Yojimbo, Merlin Project, Marked 2 nvUltra, Reader and Author which are developed by original signatories of this manifesto, are all linkable.

Why should information be linkable?

Because that way you can more easily , and “randomly” (in the sense of “RAM”), get back to it, without even having to search or click through the destination software (service). Easily implies that fewer commands are required, less time is required, and fewer demands are placed on the brain’s executive functions (see Wikipedia” (consciousness, working memory, attention, etc.) Our executive functions are very limited, very precious.

Research shows that humans perform better when they can quickly access information. Clicking a link is easier than searching.

Here are some examples of benefits of rapid information retrieval of multiple, analogous types. I mention them because you can easily understand and generalize from them.

• Expert chess players can quickly encode and recall chess boards. Similarly, experts in all fields have long-term working memory. (See Motivation – Linking Manifesto).
• QR codes are a handy way of getting a URL. Point your camera at one and you can quickly get to it, without needing to type in the address.
• Why do people like solid-state drives (SSD) so much? Mainly because they allow users to efficiently and robustly encode and retrieve information.

Ubiquitous linking can actually facilitate analogous benefits: rapid information retrieval, and even rapid encoding of information address.

What is the problem addressed by this manifesto?

Seth Godin and others have argued that switching contexts, including to search for information, is time consuming and distracting. Clicking an aptly positioned link is much easier. However, whereas links are ubiquitous on the web, local software (such as an email app or todo list) often do not enable users to create links to their objects (i.e., a link to the email or task). This is particularly the case with software from major OS vendors. Yet hyperlinks to local information (including cloud-synced locally represented information) would also be extremely helpful.

This calls for a Copy Link function and underlying link automation to be ubiquitous — in all software that presents persistent , re-accessible information to users. Realizing the mission of this manifesto would allow users to paste links to key information in the context where they need them. This in turn would allow them to search less, and to retrieve prior information faster. It would help keep users “in the zone” (aka focused, in “psychological flow”).

This would also facilitate sharing of information. A link is a direct reference to a resource.

Other benefits of linking are discussed in Motivation – Linking Manifesto.

The technical requirements are discussed in Technical Requirements – Linking Manifesto.

Why is linking not yet ubiquitous?

Although many independent developers understand the value of ubiquitous linking (and support the requirements of this manifesto), there seems to be a lack of understanding, or at least of execution, on behalf of largest software companies more generally about the importance of protecting the attention of consumers, and how linking can protect attention. Many smaller companies also fail to understand the value of linking.

It also seems that some companies have a vested interest not to (conveniently) provide direct links to resources. Some large data companies seem to prefer to serve information to users rather than have them directly access it.

This may also partly simply be due to ignorance. We are publishing this manifesto to educate the world about the concept and benefits of a world in which links are ubiquitous

Examples from data companies: cruft-ridden or absent links

Large data companies would rather track users than conveniently and transparently deal with hyperlinks. One way in which they do this by serving URLs that include tracking information. When you search for information on their web services, they tend to serve you a URL with much tracking information. That information is cruft, making the URL unwieldy; it also makes it somewhat difficult to tell that two URLs are equal. (Search for information in Google, Twitter, Facebook, Amazon, LinkedIn and GoodReads as examples).

Facebook , by Meta Platforms Inc, is an example, as illustrated in this Hook productivity facebook page](https://www.facebook.com/HookProductivity/posts/603066601148601).

1. When you publish a “post” on Facebook, the hyperlink of the post is very hard to see. The name of the link to the post is its date stamp. The link is in small font. Many users ignore that feature (i.e., they don’t realize they can get a link to any post by clicking on the date stamp).
2. When you click on a Facebook hyperlink to a Facebook post, the web page that Facebook serves you has a generic title [<n> Facebook], where <n> is a variable number controlled by Facebook]. Here is an example of such a post: https://www.facebook.com/HookProductivity/posts/603066601148601. The name served by Facebook does not even include the time stamp. This means if you are to bookmark this post, you have to give it your own name. Also, if you look at your tab bar, you can’t distinguish one tab-post from another.
3. Furthermore, when you paste a remote hyperlink into Facebook, such as CogZest – Thrive in the Sea of Knowledge , Facebook translates its URL to a very obscure l.facebook.com address, which contains a bunch of tracking information, such as `https://l.facebook.com/l.php?u=https%3A%2F%2Fcogzest.com%2F%3Ffbclid%3DIwAR0GH2dFGFZiQUdaz-umi8As07miIIhJJzfsCneJ-G3lbnbGF0GtrSMQTuo&h=AT2W9oCdeki_BTJYDcmAOjuctDprEKq1glh-IENdBmvRyuaDIo5nmSCMXepB54IYzDDDPt89p_Lo6oP3bO16HB8HADA-S94O3iX3q8_YrwSx6I6Bz6ls_FXNVVEI5CQUXXoI4T0&__tn__=H-R&c[0]=AT3nsfXgE4_XFXno0nxEVAmJMz-t6LOR_eRNxEzDK_i5D2caMq_W7xiAIwSzqJ2SWcTEURADhhKldSn-7AlNicFpQBBVwpeE6KLSuylwyL_7QrCsXP-HFygSGx0UuJaRDRVV`.

This is inconvenient and violates your privacy. Every time you click on this link, the website knows you are doing this. This is not just a feature of the software, we know that Facebook mines and utilizes the data to build a model of each user.

Example: Apple’s apps for Mac, iPhone and iPad

Apple provides very little support for linking in its apps. Apple’s Notes, Messages, Reminders and Mail apps (to name a few) do not provide a Copy Link function. Apple Notes and Apple Messages do not even have automation to get a persistent ID of items in Notes, Messages or Reminders that works across iCloud devices. (For example, the API to get the ID information provided by Notes does not work across Macs let alone other devices.) If one could link to individual messages, one could paste those links in contexts. That would save a lot of note taking and be a great memory jog. (For the record: there is a work-around to the Notes and Reminders limitations.)

Where iOS and iPadOS do provide “Copy Link” functions, they (a) are buried low in the list of “sharing” items, (b) do not return a fully formed link including the title, they simply return an address (URL) without the title. So if you paste that “link” you can’t easily tell what it refers to.

Take a look at the Podcasts app for instance. Click on a podcast, hit the share button, and try to find the “Copy Link” function. Here’s an example of what you get: https://podcasts.apple.com/ca/podcast/the-psychology-podcast/id942777522?i=1000538281077. Can you tell what that refers to? Not specifically. Here’s a better link name: Ron Friedman : Reverse Engineering Greatness | The Psychology Podcast. You can’t even conveniently construct the link yourself from the Podcasts app because it does not allow you to select text on the page? Surely, Apple has an agenda here, but what is it? Same goes for Apple News items and other items. Whatever their rationale, it does not seem to be user experience. Either Apple misunderstands the importance of linking, or they understand it but have some non-public motive to prevent users from conveniently accessing information via easily-obtained, properly formed links.

Luc Beaudoin, editor of the manifesto, exchanged emails with Steve Jobs in 2010 about cognitive productivity, including linking. Jobs even requested a white paper of Beaudoin, which Beaudoin provided (over 30 pages). It’s impossible to tell Jobs would have acted on this information had he lived longer.

Apple gives itself an unfair competitive advantage over other Mac app developers

Whereas for many of its apps, Apple does not publish a Copy Link UI or API, “under the hood” it does have methods for uniquely identifying all the objects in those apps which it does not share with developers.

For example, if you receive or send a message containing a date (e.g., “December 16”) in Apple’s Mac Messages app, you or the recipient can click on the date and macOS will create a new Calendar entry on that date. The entry will contain a back link to the message, like this one:

sms://open?message-guid=ABCBB940-08A7-4FC8-8FDF-DF32CEB4234E

However, Apple does not share an API for Messages that would enable other developers to get the message ID. As a result, developers cannot extend Apple Messages app to be more helpful. It is virtually impossible for users or developers to access the ID of prior messages. Obviously, it would sometimes be extremely helpful to be able to reference a particular message , to see the context of , say a legal decision , commitment or action.

We’ve already mentioned above that Apple does not provide a way to get an ID for a Note note that works across macOS instances; but it is certain that Apple does have the ID information under the hood and uses it. (Otherwise it would be impossible to delete notes across devices).

Time and again, Apple gives itself an advantage over other Mac app developers.

However, Apple is not alone. For instance, Microsoft Outlook on Mac does not provide an API to get the RFC-5322 compliant ID of emails it manages. Apple does. That allows developers to implement interapp communication with Apple Mail app.

To Apple’s credit…

However, to Apple’s credit, macOS, iOS and iPadOS have automation frameworks that enable inter-app communication and sharing of links — if developers are willing to use it for this purpose. So the ball is in the developers’ court, on those platforms, to move on this manifesto. All Apple on its side needs to do is to provide better support for linking in their own apps. The situation with others operating systems may require more work from the OS developers themselves.

What is possible?

The requirements of this manifesto are all within simple reach of most software developers. In the vast majority of cases, software already has internal means of identifying information presented to users. For example, in order to implement an email app, once must “under the hood” process the RFC-5322 compliant ID of each email. Making this ID available to the user is typically very straight forward. Enabling users to open emails based on such an ID may be more or less simple.

Many Mac app developers have found that creating an API for copying links only takes a day or so. Creating a URL scheme is typically relatively easy, particularly for file-based apps and email apps. In some cases of course it is more complicated.

So, a world in which almost all user-accessed persistent information resources can be identified with a URL and name only takes the will of developers.

What should people do now? To whom is this manifesto relevant?

This manifesto is relevant to anyone who uses general purpose computers (laptops, desktops, smartphones, tablets, etc.) that present re-accessible data. We should all be advocating for this.

As a user /consumer of software, if the developer of your favorite app does not provide Copy Link and related functions specified by this manifesto, ask them if they would. Point them to https://linkingmanifesto.org/ . Mention their competitors who do support these requirements.

This manifesto is relevant to technology journalists, bloggers, podcasters, etc. We hope they will translate this information to their audiences, and help them understand that Copy Link is as important as the basic “Copy ” and “Paste” commands. You may contact the editor of the manifesto. Read the blog posts, press releases, and other communications of the participants in this manifesto. If you want to dig even deeper, there is a bibliography in Motivation – Linking Manifesto.

What’s the controversy here?

We can only speculate as to as to why the problem hasn’t been solved, as discussed. My speculative answers are tied to current societal concerns. However, the plain facts are that the ability to reference and access information via links is extremely helpful, and gigantic software companies, and even smaller ones, have yet to prioritize this. In neglecting linking requirements, software developers are neglecting the needs of their users. These needs are based in inalterable psychobiology (limited working memory, distractibility, etc.) and cultural requirements. See Motivation – Linking Manifesto.

What is the history of this problem and manifesto?

Ted Nelson and Douglas Englebart discussed hyperlinks decades ago.

In 1989, Amy Pearl published “Sun’s Link Service: a protocol for open linking” in Proceedings of the second annual ACM conference on Hypertext. Her paper expressed many of the requirements of this manifesto, and some additional ones not mentioned here. The About page of our manifesto concludes with the last line of her paper: “We hope to see linking, and attendant hypertext capabilities, as much a standard part of the computer desktop as the cutting and pasting of text are today.”

The history of this specific manifesto is described in About – Linking Manifesto.

What’s the difference between an “originator” and a “signatory”?

Originators are the people who, before the launch, participated in and signed onto the manifesto.
They are the original signatories. Subsequent signatories are simply referred to as “signatories” in the manifesto. The distinction is similar to the Agile Manifesto’s distinction between “authors” (originators) and “signatories”.

Will the manifesto be static?

Once published the manifesto is read-only but additional signatories will be added to the manifesto. Same principle as the Agile Manifesto.

Technical questions

Do file-based apps need to provide their own proprietary schemes for copying links Copy Link?

Ideally, an app provides a UI for getting a file://URL from the currently open foreground file, or the selected file. Based on this information, the user can do all kinds of things, like create an alias, find it in Finder, etc.

If a file-based app provides a proprietary link to its resource, should it also provide a file:/// URL to them?

At least through automation. That way users can access the URL of the foreground file through automation, without the dev needing to provide a Copy file:// Link UI. A typical case for this would be apps that sync files via the cloud or some mechanism to be made available across platforms. Their proprietary URLs can then be used across devices.

What about universal links?

Universal Links are described on Apple Developer website. This manifesto does not advocate any particular URL scheme. However, we do advocate for links that can be translated across devices. In particular, if a developer provides web URL and local app URLs (like OmniFocus:///someID), then the developer should publish explanations about how to map one to the other. That way users can manually or with automation translate one from the other.

What about deep links to specific locations in documents?

Ideally, software that presents hierarchical data or a standard read-only format (such as PDF or media players) should also provide a method to copy links to the current location in their resources — if not through the user interface, at least through automation (to facilitate automation and inter-app communication).

Some PDF apps already support this via automation, such as PDFpenPro and Adobe Reader. Apps like OmniFocus have nested data where each specific object has a URL.

Other example of deep linking are: media players (with time stamps), and web browsers (to HTML anchors). QuickTime and YouTube are other examples.

For many other apps it is not as obvious how deep linking would be provided, and that would be done on a “best effort” basis.

What are the detailed technical requirements of linking?

The technical requirements for ubiquitous linking are quite simple. They are described on the Technical Requirements – Linking Manifesto page.

Are there relevant disclosures/ disclaimers ?

This page written by Luc P. Beaudoin as an explanation of the manifesto, it is not part of the manifesto itself. Other contributors may view the issues differently.

As noted in the manifesto, I am co-founder of CogSci Apps Corp. which makes Hook. See about me for my bio and affiliations.

Many of the signatories are business owners or professors whose careers could be improved by this manifesto. Doing great works that “bends the universe” in a beneficial direction can help the careers of those who participate in the bending.

Readers of this manifesto also stand to gain from having better software tools for deep work.

for more information

For more information email me at lucb at this domain, or message me via twitter @LucCogZest. I’m easy to find