Preliminary Discussion, Part 3 - Deliverables and Communication

[Lilith-NightRose]

Navigation

This discussion is divided into four parts:

Introduction
Governance Discussion
Release/Communication Discussion (you are here)
Caesium Universe Proposal (wip)

Introduction: Release Day

Picture this: despite all odds, everything has come together. The dev team has made a feature-complete version of Thorium Nova, and with it, we have a fully developed universe to go with it. Alex (or another dev) packages up the beta release and links it on the Thorium Site and then... what do we (the narrative team) do? We have this big beautiful galaxy to share. How do we do it?

Groundwork

Okay, we have the basic groundwork for our workflow: preliminary discussion happens on Discord and GitHub (via Issues and Discussions). from there, actual writeups happen in the GitHub repository (probably. More on that in a minute). But what happens after that. Do we want the classic pretty-lookin' sourcebook available as a PDF on the website? Do we want to direct people to a website or wiki page? What should be considered the "authoritative" source as we engage in post-release lore updates? And if we do want to use the GitHub wiki, at what point in the project workflow should we move from the Repo to the Wiki and back?

My Proposal

Okay, so with all those problems written up, here's how I think it should work: the repository should have two, maybe three "core" branches: a "planning" branch, an "editing" branch, and a "release" branch. Worldbuilding documentation ideas should start here and be written in Markdown. The Wiki (GitHub or otherwise) should not be where ideas are developed, rather, it should serve as a community-focused way to navigate the existing lore. I also think it would be pretty fun to release a PDF sourcebook alongside the initial release of Nova, then release PDF supplements to go with ensuing feature upgrades.

The Repository

As discussed above, the project itself will have three upstream (I think that's the term?) branches: planning, editing, and release. The branches and their purposes are described below. Text should be written in markdown and merged into GitHub. For community members who don't feel like learning the Git feature-set and the basics of Markdown, folks are free to place text as an issue, in a discussion or via discord, and someone who is facile with the repositories will copy it over.

Planning Branch

The planning branch should be where details of the worldbuilding are hammered out. On this branch, details are subject to change, ideas are open to exploration, and concepts that are not yet compatible with the Nova initial featureset can be explored.

(as an aside here, I originally talked about how to structure the repository and how to append to it, but it got wordy and my thoughts are complicated enough that I think it deserves its own discussion, so it has been removed)

Editing Branch

Once an idea has been thoroughly hammered out and accepted by the community, it can be moved to the Editing branch. This is where we work out specific details, word choice, and spot any minor continuity errors that may show up, as well as pulling in any missing cross-references. Note that cross-references should not be too dense. Deep crosslinking should be saved for the wiki.

Release Branch

This is the finalized branch, off of which all deliverables should be based. Furthermore, if a flight director or mission builder is looking for a definitive "canon," this is where they'll find it. If there's a conflict between the documents in the release branch and the wiki, the release branch is considered to hold precedence. The release branch should only have documentation and narratives that are compatible with fully released features of Thorium Nova

The Wiki

If the release branch is "the world" the wiki is, well, a wiki for it. Information here should be repeated, deeply interlinked, and generally formatted for ease of comprehension for someone who's basically familiar with what thorium is and how it works. Unlike, say, a wiki for a novel series, it can copy bits of information wholesale from the branches, but ideally writers on the wiki are also doing work to synthesize and summarize information that maybe gets a little overwhelming from the repository.

The sourcebook (and supplements)

The idea here is to have a static "starter kit" for Thorium Nova (and maybe one for thorium Classic), that combines instructions on how to use the software and operate missions with an introduction to the thorium universe we've built. To get a sense of what I'm talking about, I'd recommend checking out the Lancer Sourcebook, though I suspect that neither Classic nor Nova sourcebooks will be quite as "rules heavy" and your classic TTRPG guide. This sourcebook will remain largely static (even with lore updates!) and will be appended by supplements that are concurrent (or shortly following) new feature releases of Nova.

Discussion

Well, this one took a little bit longer. Apologies for that. I look forward to hearing feedback! Next up: my proposal for the Caesium Universe for Thorium and Thorium Nova!

[alexanderson1993]

A few thoughts:

fully released features of Thorium Nova
I think it makes sense to treat the current alpha/beta of Thorium Nova as the definition of "fully released". That allows the narrative repo to maintain progress while Thorium Nova is still under development. For the initial part of development, we can consider any in-discussion features as part of "canon" so we don't get stuck while features are in development.

On the other hand, I don't think effort should be made towards a PDF sourcebook until after Thorium Nova reaches beta state. The release of the PDF source book should coincide with the Thorium Nova 1.0 release.

The Lancer sourcebook is great inspiration. I would love for the sourcebook to have excellent layout, typesetting, and illustrations. It's worth it to me to put in the effort to have an impressive finished product, as that is an easy demonstration of how Thorium Nova is a serious tool for serious users (while also being friendly to casual users). This is somewhere it would be worth using Open Collective funds.

It would be interesting if the sourcebook included content about running simulations without the software at all. No idea what that looks like, just an idle thought.

I would love to build in some/all of the source book directly into Thorium Nova. There are two places where sourcebook materials could be included:

• The "How-To Guide", which should include any material which is universal to any Thorium Nova universe and should be sufficient to get a beginner started without reading the full sourcebook itself.
• Some kind of encyclopedia that is built into plugins, allowing for universe-specific material to be included. I don't know exactly what this looks like yet, but it should be included somehow so plugin authors can explain their universe with would-be adventurers.

To be clear, none of this supersedes a PDF sourcebook which contains materials from both. But I do want it to be possible for all of this information to be obtainable from within the Thorium Nova app. The workflow should be as easy as "Download the app, start a flight, connect friends computers, start playing."

Another thing to consider is other physical objects that we can use as part of the narrative, to enhance the experience. I'm thinking of things like this paper DRM that came with Monkey Island: https://www.oldgames.sk/codewheel/monkey-island-2-mix-n-mojo

One of the appeals of the brick-and-mortar space centers is how they can integrate props, coded messages that have to be decoded on paper, and other real-world experiences into the simulation. Many of these could be offered as digital downloads that they can print out and prepare themselves (origami props! I'm only half-joking) and if we wanted to get really sophisticated, we could assemble hardware kits with high-quality props that people could purchase (at-cost or for a small profit). This is obviously a long way out, and has legal and financial considerations that would need to be sorted out.

---

The Narrative git repository should use pull requests to accept any changes. It should be rare for anyone to commit directly to the editing or release branches. That makes it easier to tell what changes are happening and to offer suggestions and have discussion when reviewing, before the branch is merged. We can train people unfamiliar with Github on how to do these things. Maybe a short video?

I've never been a fan of Github's wiki. It's kind of difficult to discover, and the materials are already going to be in the repo anyway, right? I would just as soon leave the Github wiki out of it entirely, but I don't feel very strongly about it so don't let me stop you if you really feel like using it.

[Lilith-NightRose]

Most of what you're saying makes sense to me.I like the very "both and" approach you're taking. I'm not 100% on running sims w/o any software, but if someone wants to take that and run with it, I'm not opposed.

I'd love to do the layout and editing of the sourcebook, once we get to that point. That sort of thing is very much in my wheelhouse, and I have (some) of the tools necessary to do it.

In terms of the wiki: I'm not strongly tied to the GitHub wiki concept. I guess where I'm at is that, in my mind, the core source won't be as beginner-friendly as, say, a sourcebook, or the 'plugin encyclopedia' you mentioned. I guess that's what I had in mind when mentioning a wiki: something that would be an easily accessible, encyclopedic reference for players. I guess that gets me thinking about the best way to include such a reference. Maybe instead of having all the info contained in a plugin, we instead give the FD a way to point to a wiki (or other site on the open web). That way, the encyclopedia can be accessed both in-sim and offline...

[alexanderson1993]

Creating a folder/file directory in the git repo and having the markdown files link between each other would be a good way to provide a similar experience to the wiki. Bonus: If we wanted, we could have the Thorium Nova repo reference those same source files somehow, without having to duplicate content. I'm not sure how that would be possible with Github's wiki, without a complicated API integration.

Again, I don't feel super strongly about it either. Gaining momentum is more important than bike shedding details like this, so I'm happy to go along with whatever you want to do.

[brentjanderson]

Long-time lurker here. 👋

Reading this and considering the broader context, and I'd like to propose that Dendron be considered as the foundation for authoring and publishing this repo.

Tl;dr

Dendron is an open-source, local-first, markdown-based, note-taking tool built as a VS Code extension.

You get all the authoring capabilities of VS Code, and tools for organizing and exporting what you write in a variety of ways (including writing your own export plugins in Typescript: You could convert Dendron notes into a Thorium plugin using a custom Dendron exporter).

I've been using Dendron myself for over two years after trying out Roam Research, Notion, Obsidian, and others. I use it not only for personal notes, but also for my own fiction writing projects, where it's been indispensable for organizing all the details and broad strokes, drafting ideas, and then collating all of that into narrative outlines. It's that bit that makes me think it's worth considering for Thorium's Narrative repo.

Why this is better than plain-old markdown that we incrementally build out ourselves?

1. You can publish the entire repo via NextJS with just a few clicks for a public, read-only website (The dendron wiki is one such example).
2. Dendron avoids broken links: If you rename a note, Dendron will update all the references to that note so they don't break. Save time, ensure consistency!
3. Dendron supports transclusion: Take a snippet from one note and insert it into another note. When you publish, Dendron will put all the snippets in all the right places.
4. Dendron supports footnotes, tables, github-flavored markdown, diagrams, and more.
5. Because you can write your own TypeScript plugins, the sky's the limit on getting content into and back out of a Dendron vault and into something else in an automatable way. Dendron ships with export plugins to plain Markdown, JSON, Notion, Airtable, and Google Docs. I've experimented with writing my own as well, and it gives you a lot of power (you're working over an AST of the whole note repo, so anything is possible).
6. There's a pretty good pipeline from Dendron -> Markdown -> LaTeX -> PDF for e.g. polished finished mission books like Lancer.
7. It's all open source, and for the most part it's just markdown, so switching costs are pretty low if it's not working out.
8. It can (optionally) enforce structures with schemas and templates (e.g. every species has sub-sections describing geography, culture, technology, etc. organized in a consistent way).
9. You could break content domains into separate vaults: e.g. one for worldbuilding, another for stories. They can cross-reference each other, but still be separate. If I wrote a story, I could fully incorporate the worldbuilding vault while maintaining a completely separate repository. You don't have to, but you have options to organize the chaos as all the markdown ideas scale and sprawl out.

Drawbacks

1. Dendron is a VS Code extension. If everyone authoring this repo is okay with that, then this is fine. If not, I think you still have to establish the tooling you want to use here (e.g. what/who is going to enforce structure in this repo? The more the computer can do that, the better - and Dendron comes with all of that setup out of the box).
2. Dendron is a community-driven project with a bit of venture funding, but I do not expect it to turn a profit. It could go away tomorrow. Being open source and with a pretty vibrant community, it's a pretty good bet that it will still be around in 5 years. Also, since it's mostly just plain old markdown, migrating to something else isn't hard to do. You'd probably lose schemas and

But what about bikeshedding?

Gaining momentum is more important than bike shedding details like this.

Dendron helps avoid bikeshedding: It has sane defaults, enforces just the right amount of structure, and lets you incrementally adopt advanced features while getting out of the way for everything else.

At a basic level, it's just a VS Code extension that puts frontmatter on markdown files and enforces a hierarchical structure on how you write those files (the same as a filesystem with folders, but instead of this/file/is/nested.md you get this.file.is.nested.md).

As narrative writing progresses, Dendron offers (but doesn't require) the stuff you need to organize the chaos (schemas, multiple vaults, plugins, etc.).

Although all of the above is possible with organic, self-driven markdown, Dendron (and tools like it) have been built with a lot of thought into making it so you don't organically build something you can't use. Using one of them gives you batteries included, and just the right amount of guardrails so you don't have to reinvent collaborative writing projects, you can just collaboratively write.

Potential next steps

1. Skim through Dendron's Concepts page to get a feel for some of the ideas
2. Walk through the Getting started page and the tutorial.
3. If you like it, initialize this Repo as a Dendron vault and start writing.

[alexanderson1993]

💯 Tools like Dendron and the other tools you mentioned crossed my mind when I wrote my comment.

[Lilith-NightRose]

Dendron seems like a really excellent tool and exactly the sort of thing that would be highly useful when constructing the narrative. I'm going to go ahead and initialize a branch to muck around in dendron with!