Lore Philosophy

Learn from the mistakes of your predecessors. You aren't special.

Stand on the shoulders of giants- some people have already done hard work, and some people know how to get energy moving.

Set a good example, and it will propagate. Bad example: Vice versa.

Make sure the data is useful, even if there will be nobody else to help you, and even if nobody else will read it.

Make sure to have fun while working on it.

Cassidy's technical writing manifesto:

  • Be concise
  • Prefer telegraphic style
    • Omit: articles ("the", "a"), auxiliary verbs, unnecessary prepositions, filler words
    • Keep: nouns, verbs, adjectives, key modifiers
  • Avoid restating the obvious
    • Don't restate types already in signatures
    • Don't summarize functions when the name is self-explanatory
  • Document what's close and stable
    • Avoid "far away" references likely to change
    • Exception: ok if lints/tests/jobs catch breakage
  • Start inline comments lowercase
  • Use periods only for full sentences
  • Use full sentences only when needed; lean on context

Data Structures

You're forever going to want to switch around between different data structures and schemas.

Prepare for migration/portability early on to save yourself the worry.

No matter the schema, some things should always exist:

  • Focus on the atomic unit of data. If something is too big, split it.
  • Information is hierarchical.
  • Information has other types of relationships too: Categories, tags, and direct links.

Of course, no data structure can ever really be enforced. Trying to force somebody to add rules, or populate with something, will just cause them to split off.

Hint: Markdown is the most portable text format these days. It's especially compatible with Discord, which is big.

Useful Tags

Point-of-contact. For example, Cor Vous owns Crimson Harbor lore. ...

Wiki Philosophy

  • Try to keep the markdown, generally, inter-operable with other interfaces.
  • Link to original sources. Display the last update time of those sources and compare them to the last update time of the wiki pages to determine when things may have fallen out-of-date.
  • Use consistent formatting for users. The most important details for contact information are their discord user IDs.

Future TODOs

  • Automate audits:
    • Contradiction audits
    • Information going out-of-date
  • Ingest information from Discord somehow
  • Check out: https://github.com/mkdocs/catalog#-theming