Software is About Promises

When publishing software, you make a promise to your users. This is true outside of software as well of course – nobody wants a beagle when they ordered a bagel. But in software specifically there are a few unique considerations around promises to deal with:

1. Software is both an abstract and real object. You can run Minecraft on a computer, but you can also make a "Computer" in Minecraft. This abstraction allows for any piece of software to technically be converted into any other piece of software given enough time and space. Speaking of time...
2. Software practitioners are significantly constrained by resources, while at the same time, software scales near perfectly. This paradox means that good (or bad) software can reach millions nearly instantly, but any piece of software will always be bottlenecked by developer time. Creativity cannot be parallelized in any way that matters.

In short, software can be anything in imagination, but must be something in reality.

That "something" is a list of features, intertwined within a noisy field of bugs. This "something" is all software: browsers, compilers, video games, open source repositories, "print hello world x 10", etc.. (perhaps this is why copycatting runs rampant in software? Good ideas are harder to come by than to recreate?)

If you let either of the above considerations go haywire, you will inevitably fail.

This is where your promise comes in.

Given your resources and goals:

What are you promising your users? And how is this promise testable?

You must be as strict as you can in your definitions. Freedom from "head in the clouds" abstractions, and the burnout of "over promise and under deliver" comes from being as clear as possible.

Let's examine a case study of what promises can do.

Case Study: Your Commonbase

Your Commonbase (YCB) is personal library science software. Personal Library Science is defined as four functions operating on an individual's library: store, search, synthesize and share.

All four functions have many strategies, some of which are objectively better than others, and some which are subjectively better than others. Let's take a look at our #1 and #2 from above in the framing of the upcoming YCB Beta.

Store

YCB Beta Promise: With Your Commonbase, you can store text, images and URLs from the iOS platform, Chrome browser, or the Companion application.

1. The abstract end goal of store is to be able to quick capture any given moment from the world into our personal library. Think highlights from a book, a particular photo, a part of a movie or song. Quick capture means running store() doesn't remove the librarian from their existing context.
2. Store is primarily influenced by the environment it runs in. Given our resources, we focused on storing from Chrome (the most popular browser by a wide margin) and iOS (partially because I own an iPhone, partially because of the Shortcuts app). It was under these constraints that we built the following features:
   1. For Chrome, the store features include: save a URL, save full page or area screenshots, save selected text.
   2. For iOS, the store features include: store from the iOS share sheet (photos or URLs from Instagram, Youtube, Spotify, etc...)
   3. For both, a Vision model is used to convert images to captions for storage.

Search

YCB Beta Promise: With Your Commonbase, you can semantic search and semantic scroll through your personal library. You can also search as you type.

(A note on semantic scrolling: Whereas semantic searching is to finding results from a typed in query, semantic scrolling is to using a vector to travel through its neighbors to find similar content. You can see examples of this in the Share Commonbase link below.)

1. The abstract end goal of search is to find the correct entries in a Personal Library while providing minimal input context. In other words, finding a personal needle in a personal haystack with minimal effort.
2. Search algorithms are really good these days, but are primarily limited to text. Meilisearch indexes combined with vector embeddings got us a lot of bang for our buck. To create semantic scroll, we retrieve entry.vector and use that as the base our similarity scoring technique. We then use a summary/details framing to link entries.

Synthesize

YCB Beta Promise: With Your Commonbase, you can synthesize your entries with your own commentary.

1. Synthesis is the most complex function of a personal library. Synthesis is the use of existing entries in a personal library to complete a non personal library related goal. Think citations in a research paper, a DJ remix, or learning deeper about a subject by adding your own understanding.
2. Commenting functionality exists on Chrome, iOS and Companion. You can thread comments and create deeply nested graphs of manual links between ideas using images, text and URLs. This constraint doesn't yet promise for audio or video, but it will in the future!

Share

YCB Beta Promise: You can share your entries from Companion, or from the URLs in titles.

1. Share is where entries leave a personal library and re-enter the world proper. This could mean something as simple as sharing a single entry, to a curated collection, to an entire library object.
2. I'm not gonna sugarcoat it, share got the short end of the stick with our resources. There isn't point in putting limited resources into share when my users don't have any entries stored worth sharing. We did enable a way to share screenshots, and direct URLs (which comes in handy all the time when text messaging friends)

Conclusion

Software needs promises.

Promises protect the developers, the users, and the integrity of the software itself.

In the case study, I directed most of our limited resources to store and synthesize, as they lay the groundwork for the future of search and share. The promises are testable by our user base of librarians, and set the tone for future development.

Want to call me out on my own promises?

Explore a public demo of the Commonbase architecture (specifically semantic scrolling) and sign up for our waitlist:

Share Commonbase

Explore the shared space of our Commonbases

Best,

Bram