Keypoints, a plain-text focussed note-taking & PDF annotation app for the Mac

This is about Keypoints, an app that I’m currently developing (it’s not available yet). @quorm encouraged me to create a dedicated thread, and I hope to get feedback on the app’s intended workflow.

From my own work in academics as well as during my work as a developer for reference management applications (refbase, Citavi & Papers) I’ve noticed that many students & researchers are trying to implement their own academic reading & notetaking workflow. On the Mac, this usually means combining apps from at least three categories: PDF highlighting, note taking and reference management. And these are just the basics (there’s also outlining, concept/mind mapping, and the actual writing process, etc). But trying to integrate apps from these three basic categories already means a lot of back & forth or scripting/automation.

My app sits in between these three categories and tries to combine some elements from them: E.g., while highlighting your PDF, the app extracts each highlight annotation as a self-standing plaintext/MultiMarkdown note, and can include bibliographic information from your reference manager.

In each note, the app includes the highlighted text as a quotation, adds page information and (if possible) fetches reference info from your reference manager. You can then add your own title/summary/comments to the note, assign it a color label, tag or rate it, and link it with other notes (all via drag & drop, autocompletion or menu commands / keyboard shortcuts). CriticMarkup support helps to further structure your notes.


One can also open a note in its own window (to review or work with multiple notes simultaneously):

All structural elements get syntax colored and are clickable so you can easily navigate your network of notes. Note connections can be visualized in a network graph (which can also be used for navigation).

Since all your highlight annotations are atomic plaintext notes, you can search and filter them freely (independent from the PDF source they came from), and gather them again in structure/overview notes. Selecting a note will also jump to its quoted text in the PDF. And clicking a highlight annotation in the PDF will select its note.

Keypoints is document-based (a document is a Core Data database containing many plaintext notes). Keypoints parses all notes & reference info into a data model to facilitate many of its features. However, on (auto)save, it will also auto-export all notes to a folder on disk, and I plan to also read from this folder. This helps to avoid lock-in and should enable basic integration with other apps/services. The app is also highly scriptable, and I’d like to develop custom export/sync scripts to facilitate good integration with other scriptable apps such as DEVONthink, Tinderbox, OmniOutliner, Papers, Bookends, or BibDesk/Skim etc.

As originally outlined in this thread, the app is based on these core principles:

  1. Free annotations from the PDF & work with them: PDF annotations only get really useful when they are extracted from the PDF. So my app gets them out of the PDF immediately, and you then interact with the resulting plaintext notes.

  2. Notes are plaintext: This ensures maximum longevity, avoids lock-in, and allows for easy integration with other apps. The plaintext notes also give you a good data exit strategy.

  3. Notes are atomic: One note per thought. This allows you to tag to the bullet point level, and it enables you to freely filter, rearrange and reuse them.

  4. Notes are self-contained: Notes should be as self-contained as possible. I.e., the note’s body text (or its metadata) should contain all relevant information (like its tags, creation date, linking & citation info, related file & annotation info, and its ID). This way, you can do lots of things with your notes but don’t loose anything. All relevant info always travels with the note. E.g., you could transfer your notes somewhere where there’s no file path info, like a database, a single text file, or an app that stores files internally using its own naming scheme. Your notes would still remain intact and can be retrieved again w/o loss.

  5. Notes keep their context: This means one should be able to easily see the context of one’s note. I.e., easily jump to the quoted text in the PDF source, and back again. Also, always keep the reference info in the note. If possible, the reference info will be extracted automatically from your reference manager.

  6. Notes can be inter-linked: Directly linking notes to other notes is crucial since this actually captures your thought trains (tagging does not). Also, by creating a network of semantically rich and linked notes, your note relationships can be visualized. The visualization graph also shows your note’s backlinks, and it can even be used to navigate your notes.

  7. Notes are human- and machine-readable: Both are important. The structured plaintext note is your data format. Having it not only human readable but also machine readable allows to build a data model from it, which in turn allows for all kinds of advanced features.

  8. Notes can be reused in other applications: It’s very important that the app (and your notes) can integrate with other apps, via import/export but also directly via scripting/automation.

13 Likes

@quorm, I’d like to continue a conversation from another thread here:

Keypoints isn’t a typical Zettelkasten program, but it shares quite a few principles with it. For example, each note has a stable & concise ID, which is also used for cross-linking of notes. But you can create links easily via drag & drop. This is also shown quickly in this little screencast:

By “Ambitious and difficult”, are you referring to the reference retrieval? My app will try to fetch the reference info from your reference manager (if possible). There’s still a lot of work to do w.r.t. bibliographic features, but I hope to support at least the scriptable reference managers on the Mac (like Papers, Bookends or BibDesk) from the very beginning.

Since the plaintext note contains all required information Keypoints can re-establish the link to the exact PDF annotation (in the PDF source file) from the plaintext note. But it currently doesn’t provide PDF links that will open the PDF (at the exact location) in other applications. This would require those other apps to support linking to an exact position on the PDF page. Or did you mean something else?

Are you referring to the fact that notes from different PDF sources can be displayed in these apps next to each other? This would be similar in Keypoints. Or did you mean something else? Thanks.

1 Like

Looking forward to seeing Keypoints in action – very interesting approach.

1 Like

This sounds wonderful!
My credit card finger is twitching already.

1 Like

This would have been super helpful while researching for my graduate degree! Best of luck, and I’ll be happy to purchase!

1 Like

@msteffens Wow, wow, wow!

What is your business model to monetize all of your hard work?

I have been using Mindmaps to perform document tabulation of a large number of technical documentation that I am preparing.

This is a very hot niche right now.

Look at all the gushing going over Roam Research the new flavor of the month.

Where will the data reside? I think this is the issue with Roam Research whereas the data passes through their servers and they cannot handle the traffic so creating this phony scarcity frenzy.

IMHO the timing is perfect. I would suggest some type of subscription model with free access to people with a .edu email to get traction. A page out of the Apple playbook.

Besides good functionality and good relationships with your customers, I suggest looking at financial sustainability.

I am still hurting over the downfall of Clarity

Another potential customer here.

Please keep us all posted and Good Luck! A lot of hard work ahead of you.

1 Like

@D_Rehak, many thanks for the motivating feedback!

W.r.t. to business models, I’m personally no fan of subscription-only models. And for me (as a former polar researcher with elongated field trips, see here) I strongly favor apps that can also work fully offline.

Ideally, the app would be free for individuals and money would come via other means (think Zotero). But as this is highly unlikely, I’d like to pursue the classic one-off license model (i.e., no subscriptions for individual users). But before I can think too hard about things like this, I want to focus on the app, make it stable and bring it into release state. As you say, there’s still much hard work ahead.

1 Like

Your suggested approach looks very appealing! I hope we can try it soon!
Extracting information out of papers and combining them to be used e.g. in a review paper or the discussion of an original paper is always a struggle. I changed my preferred workflow quite often…
From my point of view (MD and researcher in ENT and allergy) the combination of the text with the bibliographical source is crucial here. Currently, I usually draft papers in Ulysses and paste the bibliographical info the text from Bookends. Correct formatting of the references is not crucial at this point - I just need to be able to recognize where the info came from later on.

What I would suggest to think about early on is the possibility of an iPadOS Version. It is so enjoyable to read and highlight academic papers on the iPad (sitting somewhere relaxed and not at the desk)…

2 Likes

The Agenda monetization model is very nice. You pay for the app as it is now, and it’s yours to use forever. If you want new features, you can subscribe for those. If they don’t strike your fancy, you can hold off.

1 Like

Something I’ve really enjoyed lately is using Readwise to review my Kindle highlights. I get a list of five every day, click through to the web app. A couple of clicks allows me to open Kindle to that book and highlight, so I can give the highlights some context, make more notes, etc.
This capability with PDFs or some sort of conduit to/from Readwise would be phenomenal.
I would happily pay a bounty when the time comes.

1 Like

Yes, the Agenda folks have found a nice compromise which I think is very fair and practical. They are smart guys, and I very much enjoyed working with them when I was at Papers Mekentosj. However, what I don’t like so much about the Agenda model is that it forces the developers to focus on features. OTOH, with the classic business model (one-off licensees), you can’t make a new release w/o major new features either. Sometimes, however, the biggest advancements lie in fine tuning the details.

1 Like

If you’re MacOS/iOS/iPadOS only, you might consider the SetApp model - the subscription w/o subscription. One subscription works for many curated apps. Includes duplicates, but I believe SetApp only pays publishers for the apps installed (so on merit). Yet, the model is apparently very strong (I gather).

To play devil’s advocate, the subscription model is very strong (IMO) if the value is high. Then it’s a no-brainer, and the financial stability helps with developerment, hiring, planning, through rough development patches, etc…

Without any idea of the work involved in the programming, I agree.

I certainly much prefer reading (esp. pdfs) on my iPad than the desktop / laptop computer. As is well-known, however, working with the data to generate new documents such as analyses is usually much more straightforward on a MacOS device.

As far as possible, I try to ensure the applications I use are cross-device.

1 Like

Agreed. For many (including me), the iPad is a crucial part in their workflows. However, I’m a solo developer, and I can only work on this part time. So getting an app into release state on one platform is already a big undertaking. Those who develop themselves probably know how long it can take to reliably implement even the tiniest features. So, yes, I’d love to offer an iPad version, and I have plans to implement this. But right now, it’s a long term goal.

On the plus side, since the app’s notes are exposed as plaintext files on disk, it should be possible to integrate with other iPad editors. That’s obviously not the same as a dedicated iPad app, but it’s at least something.

2 Likes

Yes and herein is the problem. Because the majority of mass public has been brought into computer literacy with easy to navigate UI’s it is reasonable to deduct that it is easy to create the software when nothing can be further from the truth and the Wizard of Oz behind the facade is either an army of programmers or a one man operation who is working their preverbal ass off.

If one wants to see something shocking go behind and look at the screens of personnel working in the hotel, airline or banking industry and many systems goin back to DOS days as they amount of work and lines of code to implement big software systems is astounding.

While it has gotten easier by building on blocks of reusable code it is still a formidable task and I think Apple is trying to blend it so one piece of code can run on their eco system.

Then this is compound by the mass consumer for some reason is under the expectation that software should be free and some have the odyssey to write up negative critics and complain about spending $0.99 > $2.99 on a piece of software while they are in Starbucks sipping their $5.00 lattes’.

Given all this why do people embark on this journey?

Well it is truly a labor of love and the thrill never ends from seeing your thoughts, your instructions being executed perfectly.

3 Likes

Great idea but please consider ways to share a set of notes with colleagues or the public - perhaps via a static site generator as you mentioned on another forum.

The difference between an app which is for personal use only vs one where you can share your work product with others is an enormous jump in utility.

2 Likes

I second that. Example, the lack of collaborative tools in OmniFocus is the reason I cannot use it for my work projects.

Sorry for my naivety…
I’m just an interested user without any experience in software development and hearing about Mac Catalyst, Xcode 11, SwiftUI and how they might make it easier to develop for both platforms gave me the impression that this would be a feasible approach.

2 Likes

This app sounds right in my wheelhouse, as I prefer keeping things in plain text. However, I do most of my PDF reading on the iPad. Would it be possible to extract the sort of typical notes I can take using a PDF reader with your app? Even just this functionality would be awesome!

1 Like

Not yet, but I also consider this an essential feature and I have plans to extract existing annotations on PDF import.

1 Like