Software should support users in exploring its design and implementation with the goal of understanding it as far as the user considers desirable.
Explorability can be in conflict with optimization and with the reuse of commodity components that add complexity in exchange for developer convenience.
HyperDoc's main role in software systems is to provide guidance to the code, through explanatory narratives and interactive execution of code examples.
Convivial software, named in reference to Ivan Illich's book "Tools for conviviality", is software that aims at ensuring its users' agency over their computation. It is software that users can adapt to their needs. Conviviality implies Open Source but goes beyond it. Convivial software must be forkable by users who are neither software professionals nor able to dedicate significant resources to maintenance. Software that has unstable dependencies is not convivial. Software that is overly opaque is not convivial either. Conviviality is therefore often associated with minimalism or brutalism
Conviviality is often in conflict with the use of mainstream technology and established best practices of software engineering. Since the 1980s, both academic computer science and the tech industry have focused on industrially produced software products, developed by trained professionals for users who value convenience over understanding and agency. This is what most of today's development tools and processes are made for.
HyperDoc implements conviviality by building on boring technology that goes back to the 1950s and has been stable since the 1990s: Common Lisp. It also adopts a brutalist approach in not attemting to hide its implementation. As you read this page, the title bar of its pane in the viewer shows you the name of the Common Lisp class that implements the page's representation in memory. That's intentional!
Another important contribution to conviviality is "don't be disruptive". HyperDoc is a new tool in the Common Lisp ecosystem. Its role is to complement the existing tools, not to replace them. Seasoned Common Lisp programmers have developed habits and, as a community of practice, established conventions. HyperDoc tries to respect and integrate them. Inversely, people for who HyperDoc is the entry point to Common Lisp should not find it difficult to adopt other coding tools later on.
Software is built in layers from components. Published software should aim at being a good component in a larger software system. Others should be able to build on your work, with as few constraints as technically possible. Ideally, your software should be fit for inclusion into large-scale software distributions such as Debian or Guix, even if you don't provide the packaging yourself.
Composability is violated by media that cannot be integrated into a larger whole, such as Jupyter notebooks. It is also often constrained by build tools and packaging ecosystems that focus on a single programming language.
HyperDoc builds on ASDF, the de-facto standard build system for Common Lisp. This means that HyperDocs can be easily integrated into Lisp-specific distributions such as Quicklisp, but also into system-wide distributions such as Guix. Cross references in HyperDoc use plain Lisp data objects, meaning that there are no constraints on linking to other HyperDocs or even to different HyperDoc-like systems.