Local-First Software

Documentation

According to Diátaxis, which calls itself "A systematic approach to technical documentation authoring", documentation should ideally have a suite of tutorials, how-to guides, explanations and references.

We can reverse-engineer that to conclude that to be able to work offline, you should have all of that information available to yourself without internet.

For references, I have a set of tools that I use:

• Dedoc. Download programming documentation for offline use
• Tldr pages. Great reference material available offline
• Man and Info Pages. The original source for reference material.
• Go Doc. Golang reference documentation.
• Recutils. I keep a personal reference database of quick commands that I use. Recutils are great because the format is minimal and can be modified using a simple text editor.

For tutorials, explanations and how-tos, I download and save various websites using wget.

Log Entries

One of the most beautiful ideas behind the original Unix, that I think unfortunately has gotten lost and is underrated, was the idea of a form of collective computing. People would gather as a group and collectively build their tools specific to what their community needs. The way Dennis Ritchie described it:

What we wanted to preserve was not just a good environment in which to do programming, but a system around which a fellowship could form. We knew from experience that the essence of communal computing, as supplied by remote-access, time-shared machines, is not just to type programs into a terminal instead of a keypunch, but to encourage close communication.

Using a collection of simple tools, users would then be able to combine these together to build the tools specific to their needs on time-shared machines.

Another obvious advantage to collectively owned computers is that you retain ownership from the bigger companies, while at the same time can unlock better optimization where these computers can live in geographically advantageous regions. For example, Solar Protocol directs users to whichever server has the most sunlight.

There are a lot of advantages to empowering users to fix issues themselves rather than someone fixing their problems for them. I wrote about it extensively in my essay The Curse of Convenience. I also see with the new LLM models a resurgence of this idea in Maggie Appleton's essay about home-cooked software. Personally, I am skeptical that LLM's will enable this revolution, but I think her essay is still worth a read!

Today, there is a communal computing system that exist, it is the SDF. It is quite old and has been around since the 1987, and it definitely marketed towards a technical audience. It hosts a set of collective computers that any member can use for any purpose (within reason). With it people have set up a Lemmy instance and Mastodon instance. You also get a free email account with it. It also comes with a shell you can SSH into and do any kind of programming that you want.

Personally, I use SDF to host my notes with git. Doing that was as simple as ssh user@tty.sdf.org -t mkdir notes && cd notes && git init. Once done, I am able to access these notes from my phone, my laptop or wherever I happen to be. To clone it locally, I just run git clone user@tty.sdf.org:~/notes. I also hang out at their Lemmy instance.

- Marc

Email combined with isync, makes it is possible to access email offline and have it synced on a regular interval.

I looked around for options for having a shared TODO list with Andrea and sometimes the most obvious solution is what is in front of you. All the local-solutions that I have used in the past made sharing difficult, and neither one of us wanted to sign-up for some third-party service nor download an app just for TODO items. Then I started thinking about how I have always shared links with myself in the past, which was through email.

Well, thanks to fastmail's web filters, I was able to set up a specific email-address that Andrea and I could use to share TODO items between each other. All email sent to that email address ends up in my TODO inbox. How do I share TODO items? Well, just add Andrea on CC and then it's done. No sign-up to a new service needed. When the item is complete, I just reply done and then my email rule will automatically drag it to my Done archive.

Similarly, I use this as my social bookmarking service. I have a special email-address and a email rule so that when that address receives links from the right people, those links end up automatically in my links archive.

These two solutions work cross-device as well. All my devices have email so sharing across BSD, iOS, and Android becomes trivial. All of them support email.

This could be further extended with interfaces that operate on the isync directory. You could then have TODO apps that use email as a backend, and what is nice is that people would not need to download an app to operate on it, so it would be a form of "progressive enhancement".

- Marc

On most browsers, you can easily download and print a PDF version of a website for offline use by using Ctrl+P.

With that, you can save and render the PDF with Zathura or Mupdf. I discovered that my undervolted laptop actually struggles with Zathura for PDF rendering, however Mupdf renders the PDFs instantaneously.

However, another technique that might be nicer is to save the website page as Web Page (HTML only) and then convert it to a more readable plain-text format. That way it is much easier to search your documentation using grep or other Unix tools.

To do so Pandoc can be used to to convert it to a Markdown page.

pandoc my-site.html --to markdown_strict -o my-site.md

Markdown is not necessarily the most readable format though, so with some extra help of lowdown, we can render terminal-readable documentation.

NO_COLOR=true lowdown -tterm -o my-site.txt

With the power of Unix, we can pipe these commands together:

pandoc my-site.html --to markdown_strict |\
> NO_COLOR=true lowdown -tterm -o my-file.txt

Then we can read it with less

cat my-file.txt | less -R

- Marc

I have began using recutils to build a database of what I have read, watched and also for references on how to do things.

The tool has a decent amount of utilities for querying data and its simple formatting means that even if recutils one day stops working, it would be trivial for me to build my own replacement.

The usage becomes simple. To find all FreeBSD specific information, I can simply run the recsel -q freebsd ~/refs.rec and I will find all my Freebsd related references. I made an alias of it so I just have to type refs freebsd.

- Marc

I read an interesting article on local-first software. I think it perfectly summarizes the issue with cloud software and the need for more offline-friendly software.

Especially mentioning Git, I think it is great, as it is a prime example of successful offline-friendly collaboration. Github of course ruins it slightly, by having PRs be done online.

I was a bit sad it did not mention the dvcs fossil though, which contains chat and forums built-in that auto-sync when you go online. It is also extremely easy to self-host.

In conversations about local-first, I often find email and/or activitypub to be underrated as well. Email is offline friendly, I have it synced offline. I also think you could extend it to have apps on top of it, like a todo list app. Activitypub could be used to push the envelope even further, as it is a system to stream activities. You could have those activities be signed locally and sent when you go online.

- Marc

I listened to a podcast, the Corercusive episode on birth of Unix with Brian Kirnighan. An interesting point was that software development today often is more about looking up information rather than building something with your own intuition. You search the answer for each query, a.k.a. stackoverflow-driven development.

I start valuing more the software that does not require that, where you can read the manual and then understand how to use the programming language.

- Marc