What Wiki Does

We aspire to write in one place a reliable description of what the federated wiki software does in order to support ad hoc collaboration between strangers within a computational medium. matrix

We encourage diverse implementations and have participated in many ourselves. As such, we have a lot of ideas for improvement but will restrict ourselves to what we know has worked.

Our most fundamental decisions are the hardest to change. We have been influenced by innovative designs of the 2010's while capturing the "wiki nature" of our original site.

Pages -- The unit of retrieval, encoded in JSON, publicly accessible, and uniformly licensed as CC BY-SA.

Links -- Name pages by Title alone without reference to location recognizing duplication as a useful feature. An external variation has two parts, the URL of a resource and the symbol that represents it within wiki.

Rendering -- The page's JSON can be exposed as hypertext by a variety of mechanisms with some modest obligation to meet the author's expectation and to fail gracefully when this is impossible.

Browsing -- A reader can navigate as they choose based solely on information with each page. Both the history of a page and the reader's browsing should be available.

Items -- A page contains a linear list of paragraph-like items of various types. Each item has a random identity assigned when created and preserved through all revisions including changing type. Within a page ids are unique and will be made so by creating a temporary alias to avoid collisions.

Editing -- Items on a page can be created, revised, copied, moved or deleted one item at a time. Whole pages can be forked close to the reader without changing the original.

Move -- An item can be moved between pages or copied to a new page leaving the source intact.

We anticipate communities with similar interests will write together in a CC licensed creative commons. The internet provides services that facilitate distribution but may not be the only mechanism. We design for pull when wanted preferring individual workflows over an algorithmic push so easily abused.

Sites -- Pages are collected into sites that may or may not be publicly available on the internet. A site represents the cuatorial decisions of a single author.

Login -- An individual may identify as the owner of a public site and thus enable their edits to be immediately accessible. A site may optionally disable editing features for readers with no intention to edit.

Origin -- A site can offer browsing of its own pages and those of others so long as those remote sites conform to conventions established by the origin.

Fork -- A page brought under persistent editorial control is copied without damage to the original but with sufficient history to meet the BY attribution clause of the license. Forked pages will be shared from the origin in accordance with the SA share-alike clause.

Hosting -- Remote sites serve page JSON based on a slug version of the page title encoded in lower case, alpha-numeric with hyphens for spaces. Sites can expect to be probed for pages they don't have and should return status 404.

Farms -- Servers are often configured to host multiple sites using virtual domain name hosting. Wildcard DNS make large families of sites practical.

Longevity -- Long-term preservation of dormant sites is expected and considered an obligation to the creative community to whom material have been licensed.

A variety of user-interface features facilitate understanding what is and has been done by oneself and others in a large and long-lived network of related sites.

Panels -- Pages are presented as panels that append headers and footers to a rendered page. A gradient flag identifies the site hosting the page. Hover and/or click will name the site and indicate unusual circumstances.

Lineup -- Panels are intentionally narrow and pile up to the right of the pages that retrieved them. A reader can rearrange the lineup at will with consequences for computations that proceed from left to right.

Hover -- Shift-hover over an item will scroll other pages in the lineup to show that item, when present, no matter those pages history.

Temporal -- Individual items may offer additional affordances depending on the type of information. For example, maps can pan and zoom.

History -- The editing history of a page is rendered as a block of small icons when this is thought to be of importance. Hover will show date. Click will retrieve a copy of the page as of that date.

Plugins -- Should page rendering encounter an unfamiliar item type it might attempt once to dynamically load from the origin a module that can complete the rendering and provide render specific interaction. The item text will be application specific markup with keywords in all-caps.

Abouts -- Plugins bundle pages explaining how to use the plugin and often include specific pages of general utility using pre-configured applications.

Sitemaps -- Sites often offer JSON formatted summaries of all pages they host. These often include excerpts from the first items, called the synopsis, and some will enable 2-way links by enumerating links found as part of the summary. An XML version might encourage search engine indexing.

Neighborhood -- Browsing is enhanced by fetching and saving sitemaps for sites encountered while browsing. Editing is expected to incrementally update the sitemaps held by the site and those locally cached while browsing.

Twins -- A panel will often note if alternative versions of a page are known to exist in neighborhood sites. These will be labeled older, newer, or same based on last edit date.

Search -- Basic search will inspect the neighborhood sitemap synopsis for keywords and then quote these as references in a custom made search result page. A more advance search will incrementally search each site's full page text by consulting a larger per-site site-index.json file.

Menu -- An origin specific list of plugin pages of general interest can be retrieved by the so-called hamburger (☰) menu. Plugin metadata indicates candidate pages.

Core wiki is a platform for plugins while plugins are a platform for community applications. Wiki's runtime data communication makes these applications long term and open ended resources.

Plugins -- We call every markup interpreter a plugin even when it is built into the core javascript. Other plugins are installed from various packages by our standard config and still more are frequently installed by Farm operators.

Sourcing -- A plugin will announce data that it has available while another plugin thus informed calls a source provided method to package and deliver the promised data. By convention, plugins look up and to the left in the lineup which creates a left to right dataflow.

Events -- A plugin can emit events announcing user interactions of interest to any other plugin offering a view into the same data. This is currently under developed capability except for a few demo plugins offering promising "scrubbing" through complex datasets.

Assets -- A site can provide uninterpreted file storage for large items such as images or videos that don't fit well into the JSON page storage. These are accessible to the general internet through a single server endpoint.

Management -- A section of the asset hierarchy is reserved to plugins that manage a particular kind of data and interpreting it for other plugins by sourcing or events. Another general purpose plugin manages user upload and download of files within their own environments.

Fundamental representational simplicity encourages automation that can read and/or write pages while preserving the owner's decision about persistent change.

Scripts -- The Frame plugin renders HTML files in an iFrame sandbox. The script tag is allowed. Messages to the iFrame's parent will be handled by the plugin providing some computational resources to the script.

Reflection -- Frame scripts have access to the enclosing page where it can retrieve page json fragments as script parameters. Parameters can include code items which can be assembled and then dynamically imported as a module.

Ghosts -- Computed results can be expressed in page json and added to the lineup as a "ghost" panel to be reviewed and optionally forked into persistent storage.

Imports -- Page json files can be dropped into a lineup where the contents can be reviewed and optionally forked into persistent storage. The system/export.json endpoint will download a complete site.

Freezing -- A plugin that assembles a result from lineup sources might offer to "freeze" this assembly as a additional property of the item.

Useful and consistent behavior within branching upgrades asserts strict constrains on some but not all functions.

Workflow -- We prefer mechanisms that are "close to the machine" and often support simple tasks with sometimes obscure workflows. As we learn more about the work the Frame script lead maybe to plugins and on rare occasion, new core features.

Releases -- Although we deny any central management code is distributed from a public repo that itself depends on evolving software like node, browsers and the internet itself.

Upward -- Compatibility issues dominate design decisions especially supporting old and specialized veresions. There is a c++ version of the server that runs on Arduino.

Administration -- A host operator assumes web duties common to any possibly multi-tenant property. This extends to configuring wiki-server by command line or config file. Plugins may provide host wide configuration by a single privileged admin user. Other users remain the sole owner of content decisions for their sites.

Portability -- An owner retains the right to export page content at will. As a backup, a site offers selective import from export.json files. Export file consistency provides the most basic guarantee that the owner can host their content where they want. Owners are advised but not required to own the domain names under which they are known.

Anciliary -- Services outside of wiki can fetch and interpret data made available by plugins such as RSS, or by the native page and sitemap server endpoints, such as federation search. A site can demand login-to-read providing some privacy for selective groups identified by various means.