docs.plus: update #2

Edward Saperia — Tue, 07 Sep 2021 13:24:46 +0000

so what is docs.plus?

We are producing open source experiments into what you can do with real-time collaborative documents beyond just writing docs - in particular, we're looking at how documents can be used as community spaces, where many people come together to create a shared, dynamic resource.

We've been busy experimenting for the past few months and have come up with two groundbreaking features that we're excited to preview with you today:

a new chat UX we discovered that's so intuitive we couldn't believe that it hasn't been made before, and
document filters, a totally novel way of managing complex, multi-author documents.

New chat UI

So imagine you're looking at your favourite collaborative doc, perhaps you are planning a project with several others, and it looks something like this:

And let's say you want to discuss the strategy for 2021, so you click on the appropriate heading in the Table of Contents sidebar, and then you are presented with this:

As expected, you are moved to the corresponding section in the document, but also a chat interface appears, with a design similar to popular communication platforms like Slack. The Table of Contents becomes a sidebar, and the list of headings becomes a list of channels. So in docs.plus, every time you create a heading in a document, a corresponding chat channel is created.

We think this "docs × slack" UX pattern is very intuitive and compelling. You can try a functional prototype at docs.plus/project; in the meantime, we're busy firming up the rest of the expected functionality - notifications, emoji reacts, mobile experience, everything you'd expect.

Document Filters

We have observed that as a multi-author document grows larger and more complex, it naturally develops an internally consistent semantic architecture based on its headings / section hierarchy. This is made to help its community of authors navigate it and understand the state and meaning of the content as it changes. In other words, it is structured to be understood not only by its intended audience of readers, but also by current and future co-authors.

This is a fancy way of saying that people tend to use headings properly! And we can do some clever things with this. Let's say you are working on this project document https://docs.plus/project, but you only care about the budgets. You can create a "document filter", either through the GUI or by editing the URL (https://docs.plus/project/budget), which shows you a view that hides all the parts of the documents that aren't related to budgets, as determined by the headings:

The document is still live and editable in this view, and the hierarchy is respected so you can see which budgets you're looking at. The fact that these exist at a legible URL means views are easy to share and collaborate on. You can even apply multiple filters at once, e.g. https://docs.plus/project/budget/2021

There are many ways to use this. We believe this functionality is particularly important for community documents, because it means users with different but overlapping interests can inhabit and maintain the same space. It also means you can better avoid the problem of communities splitting up as they grow or change. Remember, with the new chat UI it can also take the place of Slack, as well as acting as a document repository.

What next for docs.plus?

We are continuing to polish these new features so that docs.plus is stable enough to be used. We're keen to have communities of people to test it out - if you're interested, do get in touch! ed@newspeak.house or @edsaperia

This is a non-profit open source project, so if you'd like to see it continue please consider supporting us on Patreon: patreon.com/docsplus

docs.plus grant report

Edward Saperia — Tue, 25 May 2021 22:23:21 +0000

so what is docs.plus?

Features we are building include integrated video & chat, embedded multimedia & livestreams, user profiles, views & filters, email subscription, integrated monetisation, and more!

We took Etherpad, a venerable and popular open source collaborative document framework, and have been developing a suite of open source plugins providing a variety of functionality that people can mix and match to create new types of community spaces based on documents.

This work was inspired by previous community document projects The Election Tech Handbook and The Coronavirus Tech Handbook, as well as the greatest collaborative project of all, Wikipedia!

docs.plus features

the basics

The core mvp of docs.plus is a familiar collaborative doc experience with a legible URL and share image so that it works nicely with social media. If you're trying to build a community around a document, this is already a big improvement on existing platforms! For example, docs.plus/sweets will take you here:

We polished a lot of core document features such as embedded links to bring them closer to modern user expectations, and fixed a load of bugs. We also developed a basic mobile experience, which we intend to come back to and improve in future.

web monetization

Collaborative documents can now support their creators! etherpad now has a coil plugin, so the community can support hosts of community sites just by using them. We also created a simple banner feature, which can suggest contributors become members of coil, or point to some other donation platform like open collective.

user profiles

A community document is a place where you'll bump into people you don't know, not a typical experience with documents! docs.plus allows users to make email verified user profiles, which can then hook into other features like chat, video, and document history. We found that seeing users' avatars was very important to make a document feel like a living space.

document headings as community structure

Communities start out small, and grow in size and complexity over time. A great feature of community documents is that they can do the same, i.e. grow organically as the community grows. Furthermore, we discovered that headings in a community document tend to reflect natural subgroups in the community itself! We took this to the next level and built infrastructure to allow us to integrate rich features into document headings:

This can be used in all kinds of ways, for example:

every heading has a videochat

docs.plus doesn't just have integrated videochats... every heading in the document has its own videochat! This takes the video functionality from being enough for one group, to being enough for a whole community as it grows. Individual community members can split into the room discussing the topic they're interested in, and work on it simultaneously, fully integrated in docs.plus.

every heading has a text chat

These text chats are persistent, part of the document. In the next few weeks we expect to roll out all the expected rich features such as emoji reacts, rich content, @tagging and - most crucially of all - push notifications. We believe that push notifications will be the key to community retention.

Another way to think of headings-as-chat is as if Slack's channel list was a document instead, with document headings as channels. All channels are self-documenting, and all parts of the document have built-in channels!

coming soon: filters

This is the next major feature on our roadmap, and it tackles the problem of what happens when documents/communities get large. Large community documents tend to take the form of sets of lists. Filters will give you the ability to use a document with all the sections that are irrelevant to you hidden away; for example, you might want to only see the parts relevant to your location. At the same time, it should look and act like a familiar real-time collaborative document. This has both tricky technical and design challenges, but will create lots of new organic ways for communities and their knowledge bases to grow.

coming soon: community governance

Most online spaces use a simple governance model of a class of administrators who have total dictatorial power. When communities want some other form of government, such as ones that take many members' opinions into account or that distribute power in non-trivial ways, communities must create external processes to support them, which tend to be onerous and vulnerable to interference. We're excited to work with the Social Futures Lab at the University of Washington to integrate their project policykit, which allows communities to develop their own models of governance in a modular way that can evolve over time.

project update

Overall, we are very excited about docs.plus, even though progress over the grant period has been less than we hoped. We have improved a bunch of underlying infrastructure, shipped several difficult features, the product is now in a great place to do live demos (try it out!), and we have made good progress on some properly exciting new features that should be going live in the next couple of months, which will take us close to being feature complete.

However, we had originally intended to do a public beta launch early in 2021, and this has been delayed for a few reasons:

One of the team has been suffering from long covid for a few months, which has delayed a lot of comms work. Happily they seem to be improving, but it seems the effects of a global pandemic are hard to avoid! Sadly everyone in the team has faced difficult circumstances, including a few bereavements.
We discovered an unexpected technical limitation to do with scaling real-time for many simultaneous users. Essentially we encountered the limits of websockets, and had to build something that allows clients to connect to the server with multiple websockets at the same time. Happily this is now up and running and seems to be working pretty well, but gave us persistent hard-to-diagnose issues with stability that stopped us from properly supporting any real users, and finally took a couple of months to fully solve.
We had to do more work than we expected improving and fixing various basic document functionality, such as embedded URLs, images, and cut & paste. Users generally take these things for granted and a document platform that doesn't have them feels a bit broken. Ultimately we don't consider working on these to be a waste of time, as they're now available for the whole Etherpad community to re-use, but it wasn't very exciting!
Etherpad itself had a rare significant update, so we had to do some extra work to make all our plugins compatible with the latest version. The update made lots of useful improvements that will make our future work easier though, so we're very grateful!
Given the sudden transition to remote working this year, we decided early on to prioritise integrated videochats as an eye-catching feature. This proved much more difficult than we assumed! While it's not so difficult to set up a very basic video experience, offering video that's robust enough for users to accept turns out to be very challenging. There's a reason Zoom is top dog, and we have developed a new and profound respect for what they must be doing under the hood to make their group video calls be so stable.

Having said all this, we've managed to run a few successful events on the platform, and we are in fact supporting one proper live project, which is the Democracy Handbook from The Centre for Democracy, who have bravely volunteered to start using our unfinished project for their community knowledge base! This project aims to bring together all organisations in the UK working on democratic reform by acting as a library of projects and research.

what’s next?

We plan to do a public beta launch once we've deployed push notifications and filters - we consider these to be essential to the community document experience, as well as things that very clearly differentiate docs.plus from existing platforms. They're well underway, and should be done within eight weeks at most.

In the meantime, we're looking to work with more early-adopter communities that would be interested in trying it out. We are currently talking with TechForGood Organisers UK, and DataKind for their Library of Social Sector Data Initiatives. If you're interested in setting up a community document like this, do get in touch!

The Interledger Community 🌱: Edward Saperia

docs.plus: update #2

so what is docs.plus?

New chat UI

Document Filters

What next for docs.plus?

docs.plus grant report

so what is docs.plus?

docs.plus features

the basics

web monetization

user profiles

document headings as community structure

every heading has a videochat

every heading has a text chat

coming soon: filters

coming soon: community governance

project update

what’s next?