10th February 2025
Version 2?
The first version of Orsn was to an extent a proof of concept and was not widely released. Now I want to get it to a more 'finished' state, one where I will feel happier about properly sharing the software. Some changes are required to make the software more robust, and I have ideas of how to make it more useful and usable, too. These are sufficiently different from what is there now to warrant a new version number and prompt the sense of a fresh beginning.
He's a man, with a plan...
I have mostly completed making updates to Orsn to use Vue 3, Typescript and a more modern text editor library, Codemirror. However, rather than simply making a reproduction of the existing version, I'm now pausing to redesign the software.
Before I list the proposed updates I want to summarise the overall goals for the software:
- Document and share research
- A creative interface for developing, organising and inspiring ideas, and optionally to 'show workings'
- Easy to use software, ideal for individuals and small teams as well as institutions
- Geared primarily towards humanities research and writing, but with support for data-based research/digital humanities
- Encourage open scholarship practices
- For knowledge in-the-making: allow for rewriting, annotation, multiple perspectives, iterative versioning
Orsn is primarily (though not only, as we will see) a text-wrangling software which uses Markdown for text formatting. Markdown is a plain text format which makes content easily storable, reproducable, editable and versionable, for example in a Git repository. It also supports the attractive and readable formatting of text for human consumption.
Using Markdown is an important part of working towards the goals listed above, in particular, 5) and 6).
Users should be able to publish an Orsn research notebook to a Git repository, where it can be accessed, annotated and further developed by others – or at least it should be downloadable for others to explore it in detail in their own Orsn application. This shouldn't be something which is technically difficult for users to do. Orsn should offer simple controls for publishing research notebooks to Github or equivalent public repositories, and for cloning projects from repos to their desktops.
Operating at a small scale like this is vital to my aspiration for Orsn to support open scholarship and inclusive research. Orsn should be an alternative to research platforms which require an institutional team to maintain, and research projects which require large funding investments and therefore do not have the option of failing. Research should be capable of being a low-stakes activity which allows for experimentation, playfulness, and learning from mistakes. And it should potentially be open to many participants, not just those sanctioned by academic institutions.
Orsn is built using web technologies, so Orsn projects can be published as websites. However, Orsn can also be used as a cross-platform desktop app, in offline mode. This maximises its potential for inclusive use. One of the goals of the software is to provide a digital-first format for research outputs, one which properly exploits the potentials of digital media and networks, and avoids the syndrome of presenting research via 'website with downloadable PDFs'. Having a web-based format of exchange for Orsn projects allows users to exchange projects for offline desktop exploration, while retaining the benefits provided by digital interactions.
Proposed features in v2:
Simpler structure
Instead of Cards, Contexts and Pages, Orsn v2 has Cards and Pages.
Cards are like index cards in a filing system, with text and images. Cards now have rearrangeable blocks for specialised content, such as formatted computer code, LaTeX, or tables – anything that can be rendered as Markdown.
Cards can be arranged on multiple 'stacks' or 'shelfs', presented as tabs
Pages are for aggregating cards, and for long-form text (and images). But they can also be rendered by extensions (plugins) for different kinds of visualisations, as Contexts were in orsn v1: Map page, Timeline page, Graph page, etc.
Each Project has a contents page for organising and presenting Pages.
All types of content have an optional annotation column.
Extensions ecosystem
Page extensions will be npm packages, hosted on a public repository. There will be a template for creating your own plugins in javascript or typescript. Authors will be encouraged to share their extensions with the community.
Card properties
All cards already have basic properties, such as title, body, author, date of creation. In v2, Cards can be assigned additional project-wide properties, e.g. latitude and longitude, height, weight, start-date, end-date, geoJSON, etc. Such properties can then be made use of in Page views which depict those Cards and their properties, for example as graphs, maps or interactive visualisations. One use case would be that Card properties are drawn from an imported standardised vocabulary.
Versioning
A more robust version of the current revisions system for cards, with an improved visual interface. To be decided whether to extend versioning support to Card Properties.
Semantic support
Orsn does not aim to be a fully-fledged platform for semantic structuring of data, as this approach is not a good fit with its overall philosophy. However, there is potential to use semantics to create relationships between entities, using established ontologies if desired. This is facilitated by the introduction of Card Properties. These relationships can then be represented using custom Page extensions. (Semantic relationships would be stored in a relational database format, to maintain the emphasis on ease of access to Orsn, with minimal setup or technical skill requirements.)
Publishing support
An option to publish project as a set of Markdown files, and export these to an online Git repository. Also, the option to load in a project from an online Git repository.
Note. Cards can be fully represented as Markdown text and are therefore easily subject to versioning. Pages may be a mixture of Markdown text blocks and other visual elements, e.g. a Leaflet map. In a Git repository, such content would need to be represented as a JSON config file, specifying the extensions to load into Orsn, and their version numbers, in order to reproduce the content described. (Just as a package.json file does in a node project.) The installation of the necessary extensions could be automated as part of the project import process in Orsn. To be decided: how Card Properties should be handled in this scenario. Properties data could potentially be exported in JSON or yaml format, which could be used for repository storage, but then imported into the Orsn database for more user-friendly use via Page extensions.
Easier Markdown experience
New WYSIWYG editor for markdown text, for those unfamiliar or uncomfortable with editing Markdown directly, as well as 'source view' markdown editing and split-screen with preview.
Decisions and Priorities
What I need most to make v2 is time, which is a costly commodity, unfortunately. If you think a go-fund-me type project to develop the software over a fixed time-span is a feasible idea, let me know.
My philosophical approach to Orsn and open scholarship prompts me to propose versioning and annotation, as well as easy online publishing and sharing, as important features. However, features like versioning add programming complexity – which is fine, but detracts somewhat from the aesthetic pleasure of a simple codebase, and its accessibility. However, I have concluded that the best way to engage other developers in this project is by allowing them to create custom extensions, so this may not be so significant...
Should versioning of text blocks be integrated into the proposed 'export to Git' feature, so that each recorded text update is written as a commit in the exported repository? Should non-textual data (Card Properties) be versioned?
Are other features, such as semantics, or something else I've failed to mention, more important?
I am strongly conscious of the potential gap between the ideals of this project and the practicalities of how people might actually use it. Do they really want to have versioning for data, for example? Do researchers really want to 'show their workings', and is it better to just focus on allowing them to share their final draft effectively?
I also want to support the user who uses Orsn for purely personal documentation of ideas and research, and for creating documents. That is how I have been using Orsn myself for many years now.
In short I need advice on priorities! If you have thoughts, find me on the fediverse @Lemmy@post.lurk.org, or send an email to: info [at] orsn.io