Weekly digest (22-28 May 2023)

I spent a lot of time this week experimenting with a range of software that we need for a new In Beta project that Ben and I are working on.

I wasn’t sure if it was worth writing this process up, but figured it may be useful for someone else, so here goes. It’s also a good way for me to wrap my head around where we’re at, as I seem to have hit a wall, and I can’t believe that I haven’t been able to find anything suitable.

We currently run In Beta on a WordPress installation, which works well as a platform to host and publish podcasts and newsletters, and as a repository for project ideas. We’ve also used to announce our unconference, which we’ve run for 3 of the past 4 years.

But I’m not sure that WordPress has the functionality we’d like. Or, if it does, it feels a bit clunky.

Here are some of the criteria I think are relevant:

• Free: because we don’t make any money from this project. A low-cost option might be OK, if it were very low-cost.
• Open-source: so that it can be self-hosted on our existing LAMP server.
• Accessible: we can’t be spending too much time managing users, so it’d be nice if it was easy for people to sign up and sign in.
• Intuitive interface: because we can’t expect anyone to jump through too may hoops to learn how it works.
• Community: a system for discussion, comment, and / or annotation. This might also double as peer review.
• Repository (or archive): a place to store – and embed – a wide range of media formats.
• Version control: because we want to have historical access to changes that are made to files and documents.
• Publish: needs to have the option to publish to the web, with some documents unpublished.

Here are some of the options I explored.

Github
I spent more time trying to figure out if Github would suit our needs, than on anything else in this list.

I’ve liked the idea of using Github (or any kind of version control system) for managing distributed knowledge-based projects, since I read this article (it’s hard to believe it’s 10 years old). I also made a short video describing a hackable curriculum using version control. I honestly believe that a version control system, like Github, could be incredibly powerful platform for managing a learning community and its ouputs.

Github consists of:

1. GitHub itself: GitHub is a web-based platform designed for version control and collaborative software development. It provides a centralized location for developers to store, manage, and collaborate on their code repositories.
2. Repositories: A GitHub Repository (also known as a repo) is a container for storing and organizing files, code, documentation, and other resources related to a project. It acts as a central hub where developers can collaborate, contribute changes, and track the history of their code using version control.
3. Pages: GitHub Pages is a feature provided by GitHub that allows you to create and host static websites directly from your GitHub repositories. It enables developers to showcase their projects, documentation, personal portfolios, or any static web content. GitHub Pages uses a branch called gh-pages or a docs folder within the repository to serve the web content.
4. Projects: GitHub Projects is a project management tool within GitHub that helps you organize, track, and visualize your work. It allows you to create boards with columns and cards to represent tasks, issues, or features. GitHub Projects are particularly useful for managing workflows, tracking progress, and collaborating with teammates.
5. Actions: Github Actions allow you to automate some of your workflow, by enabling certain actions to be performed when other events are triggered. I haven’t looked into this too much, but it seems like automating some parts of a workflow would be a good idea. Github Actions are free for public repos.

In summary, GitHub is the overarching platform that provides version control and collaboration features. GitHub repositories store code and related resources, GitHub Pages allows you to host static websites from your repositories, and GitHub Projects provides project management capabilities within GitHub.

People use Github to coordinate large groups of people who want to produce a body of work that can be expressed in code (just another language), that includes a peer review workflow, and options to publish information related to the project.

One of the most powerful features of Github is the ability to clone repositories, where anyone with the inclination can reproduce everything in a repository on their own computer. They can then do anything they want with that information – edit, copy, delete – and even contribute some of their changes back to the central repository, which is then available to be cloned onto everyone else’s personal machine. And there’s a peer review step where a community of editors can . Collaboration is also built into the system, with the ability for anyone in the community to comment on, and contribute to, work being done by other members of the community.

And you don’t have to participate in that process; you can simply pull down a complete version of the repository, disconnect, and now you have a full working version of everything you wanted.

It goes further than that. Imagine I have a ton of content on my personal computer. An annotated archive of articles in my field, concept notes, presentations, audio recordings, and so on. And I’d like to contribute that in a structured way to my community of peers. How would I do that? With something like Github, I could merge it all into the central repository, which would then be cloned onto the personal computers of everyone connected to the repository. They could then choose to keep all of it, some of it, or none of it.

Another use case might be that everyone in that community is working on something, from big things to relatively small things. If you make a note on a podcast that you’re listening to, I annotate an article I’m reading, someone else shares their lecture slides, and so on, could those fragments of information move into a feed that everyone has access to? And not only in an ephemeral way like a Twitter feed, or someone’s blog that you follow; it would literally be a part of your own system of notes. And you get to contribute to those things too, by adding your own comments, raising issues for further discussion, and merging your ideas into the general conversation.

Github – and most of the integrated services it provides – is free for anyone to build with. And even though it’s not a platform that we can install on our own server, Github isn’t going anywhere. It’s one of the largest code repositories in the world, used by software developers to coordinate software projects that entire industries are dependent on. But even having said that, we’d be able to export all files and documentation in markdown, which means you could import it to anything else. Choosing Github is unlikely to be a disadvantage in time.

Unfortunately, Github isn’t intuitive. It’s not even intuitive for people in Computer Science, who work with version control all the time. It would take a lot of time and effort to learn how it works. The value of putting in that time and effort would need to be obvious to anyone who was interested. And I’m not sure that I can make the case that it’s worth spending the time required to get this up and running. I still think that this is the ‘best’ option, even though it’s not the best option at all.

Gitbook
Related to Github, is Gitbook. I really wanted to like Gitbook because of the integration with Github and the functionality that this brings, including a more user-friendly and intuitive interface to Github features. It’s not as modern as Outline (see below) but is pretty clean and attractive nonetheless.

Gitbook seems to have more collaboration features than other wiki options I looked at (see, for example, Wiki.js below). For example, you can comment on documents at the line-level, and other members can be notified through the comment.

Unfortunately, Gitbook can’t be installed on your own server, which means we’d lack control of the system and therefore of the project. And they could change the terms of service at any point, although you could just move to something else, as everything consists of text files in Github.

There is a free version of Gitbook but it’s only available for a single user. And some of the more useful features and publication customisations are only available in the paid version.

Outline
The next most promising option, after Github, was Outline. Outline is an open-source option, which means you can self-host it on your own server. More on this later.

I signed up for a test account that I could experiment with and was immediately impressed by the speed of the platform. It has all the features that I think would be useful for developing a learning community, managing a workflow (albeit at a very basic level), publishing and reviewing content, and

I spent quite a bit of time experimenting with Outline and really came to enjoy working with it. It’s intuitive, responsive, and pleasing to the eye.

It’s a product that’s in early development, which means that some expected features are missing. But it also means that new features are added pretty quickly.

However, the technical requirements for installing it on your own server mean that our existing LAMP stack isn’t an option, and we’d need to switch In Beta to a more expensive (much more expensive) server solution. And simply installing and maintaining Outline is beyond either Ben or I, which means we’d need to find someone with the knowledge and skills to manage it.

Wiki.js
The other option, fully open source and could be installed (I think) on the In Beta server, is Wiki.js. The current version looks decent, but there’s a new version in the works, which is good to know.

I played around with the demo for a while, but didn’t love the experience.

But I wanted to give it a proper go, so tried installing it on my local machine. And even though the instructions seemed simple enough, I couldn’t get it to work. Considering that this is a computer I have full access to, and I can’t get it running, didn’t inspire me with confidence to get it up and running on a remote server.

I think that Wiki.js has some potential, but it’d be hard to swallow, given that it seems to fall short of the user experience I had using Outline, and of the power and functionality of Github. It seems like a great wiki that’s good at what it does, but I’m not sure I can make the case that it does what we need. If I managed to install a local version and really experiment with the features, I may change my mind.

Here are a few other options I briefly looked at.

• Retype: Can be self-hosted but is too much of a technical challenge for us. And the free version only includes 100 pages per project. This might actually be OK, but I can imagine a scenario where this isn’t enough. This also has integration with Github Pages, which is nice. Retype might be worth exploring in more depth at some point.
• Ghost: Can be self-hosted. But I think the technical requirements might be challenging. And, it’s close enough to WordPress that I can’t help thinking we’d just keep using WordPress.
• Bookstack: Possibly too simple, as it uses a book paradigm and outputs seem to be limited to that format. However, this might be worth looking at again, since it does meet most of the requirements for the project.
• FOAM: Too technical. Also looked at this kind of personal knowledge management project, which is a lot like FOAM or Obsidian Publish. These options don’t meet all of the requirements but would be interesting to explore nonetheless.

There you have it. After several weeks of intense experimentation with a lot (I didn’t even mention all of the platforms I looked at in the list above) of platforms, I don’t feel any closer to a solution. Github seems like it ticks almost all the boxes, but the barriers to participation are probably too high for even the most committed community members. Outline is too expensive. Wiki.js may be suitable but I can’t get it working on my personal machine. Gitbook is limited.

So it’s back to the drawing board. Sigh.