Local-First Software

According to Diátaxis, which is a self-denominated "systematic approach to technical documentation authoring", documentation should ideally include a suite of tutorials, how-to guides, explanations, and references.

To truly be able to work offline, it is important to guarantee access to all of that information without needing the Internet. For tutorials, explanations and how-tos, I download and save various websites using wget.

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

• Dedoc. Download programming documentation for offline use.
• Offlinetools. Tools to stay offline.
• 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.

Log Entries

Portability is a very underrated quality.

Typically, we have a set of a few tools that help us get on with our life: maybe that is a GPS, a messaging platform, a design tool, etc. When the tool we use is only available on one platform, then we are coerced into using only that platform and ceding our agency to it. When we have software that is portable, however, we are free to leave a platform and choose another. It therefore empowers the user, giving us a voice (and a choice).

Portability and compatibility tend to be the lowest of priorities for a tech company, that is unless companies find themselves obliged to build software with these two qualities in mind.

One way to make modern toolmakers prioritise portability and compatibility is by setting regulation and standards. While some argue against these type of impositions on businesses, portability and compatibility standards would also benefit companies as they would also be able to make use of the diverse tools built around these standards. However, companies would need to relinquish control, the very same control that has been taken away from users. This generates an interesting phenomenon by which adding some restrictions to what we can do when we run businesses, allows us more choice and freedom in other ways.

Another force to provoke change is through consumer demand and the market. The dominance of Internet Explorer once made it so that developers accounted only for the specifications and needs to run on Internet Explorer, making access to the internet via other browsers more difficult, and at times impossible. Internet Explorer could also leverage its dominance to set standards that permitted it to perpetuate its monopoly and, in a way, force individuals to use it. However, the growth of alternative browsers eventually forced developers to account for more than one browser. It also forced Internet Explorer to start playing nice, as it could no longer solely influence the established standards.

It might be worth asking ourselves how portable a piece of software is when we choose to use it, as well as reflect on the degree to which depending on certain software can lock us into one way of doing things or into a closed ecosystem controlled by a single vendor. And not just the software itself, but also the data it generates.

- Marc

One of the most beautiful ideas behind the original Unix, that I think has unfortunately gotten lost and is now underrated, is the idea of a form of collective computing. People would gather as a group and collectively build tools. 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 bring these together on time-shared machines and build solutions to meet the needs of their communities.

Another obvious advantage to collectively owned computers is that you retain ownership from the bigger companies, while at the same time still unlock better optimization permitted by scale. For instance, these collective 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 exists, it is the SDF. It has been around since the 1987, and it is 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 a Mastodon instance. It also comes with a free email account and 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 or my laptop, 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 to build a shared TODO list with Andrea and sometimes the best solution is that which is right 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 a few days ago 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 emails sent to that email address end 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 through 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 produce 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 begun using recutils to build a database of what I have read, watched and also for storing 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've been interested lately by the energy usage of software.

Since my current energy usage is invisible to me, it is hard to actually grasp just how bad the situation is. But I often am amazed at how inefficient many solutions are, they offer very little gain.

For example, to ensure that a service is always available, at my old job we had 3+ servers running in parallel, just in case one server hall gets hit by a tornado or other disasters.

Most services do not even need 99.99+% availability, they'd be fine with just two of those nines. Maybe that's what we should strive for instead?

Anyways, if we want to understand how we can do better, it is good to understand the energy footprint right now.

After some investigation I came by websitecarbon.com, which is extremely easy to use and gives some rough estimations. It estimates the cost of:

• Data transfer over the wire
• Energy intensity of web data
• Energy source used by the data centre
• Carbon intensity of electricity
• Website traffic

It links to Sustainable web design: Estimating digital emissions which I will need to take a closer look at.

I also asked a Permacomputing groupif they had any recommendations. Almost immediately I was recommended a few tools for measuring energy usage:

• watt-wiser
• scaphandre
• kepler

Excited to dive deeper into these resources and see how I can better understand and optimize.

- Marc

I listened to a podcast recently, the Corercusive episode on the birth of Unix with Brian Kirnighan. An interesting point made during the talk was that software development today 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 have started 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

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.

I am happy the authors mentioned Git, 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, though, that the article did not mention the dvcs fossil, 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