Home

👋 Welcome to the Boxo wiki!

Purpose

This is in-progress but is intended for longer form documentation that doesn't need to go through the PR flow and that should be more discoverable than text in an issue.

Pages

See the sidebar to the right for current content.

Meta

Why use Github wiki for documentation?

👍 Pros:

1. Have full audit/version history
2. Biases towards making changes/updates without incurring friction from the PR flow. Documentation is an area that usually is less catastrophic if you mess up and also something developers take less enjoyment out of. As a result, it makes sense to remove barriers here.
3. Can easily edit with multiple interfaces (including Github GUI)
4. Renders a highly visible table of contents by default so we don't spend time doing this manually or agreing on the markdown tool to do it for us.
5. Lives within Github where all the rest of the development work is done (no separate tool).
6. Can easily link to sub-sections of a document

➖ Cons: TODO: discuss any options to offset these.

1. Doesn't allow inline commenting
2. Doesn't allow a community to propose a change with a PR.
3. One can't easily get notifications of changes by "watching" the repo.
4. There is no way to organize pages with sorting or directories
5. While a strength above, it means that an accompanying documentation can't be in the PR for making a change
6. Renaming a page causes all existing links to break.

Other options that were considered:

• Notion
  • 👍 Nice editing interface for making more polished docs
  • 👍 Inline commenting capability
  • 👍 Notifications
  • 👍 Seamless rename handling
  • ➖ Separate tool outside of github
  • ➖ Version history and revert isn't as clear/precise as with git
• Markdown files in a "docs" directory
  • 👍 Stay within github
  • 👍 Notification of changes
  • ➖ Friction of PR flow since we protect the main branch
  • ➖ Github rendering isn't as good since don't get nice/clear table of contents
• Github issues as docs
  • 👍 Stay within github
  • ~ Can add comments to the stream
  • ➖ Can't link to specific sections within text (can only link to a specific comment)
  • ➖ Clutters issue tracker and inflates the number of "open" issues

Examples of good github wikis: https://github.com/MyHoneyBadger/awesome-github-wiki

Why weren't Github wikis used in the past?

1. changes can't be updated via PR → over time wiki gets out of date to the point it is easier to delete it and write ./docs from scratch
2. no way to get pinged for a review when someone changes it → no peer review → quality suffers

What documentation is in scope?

In scope:

1. Historial FAQ like "why boxo exists" and "why X and Y are in boxo",

Out of scope:

1. Docs that guide a user on how to use the code like ./docs/tracing.md into Wiki.