Guide to Editing Docs

Hello! As you may be able to notice, this docs site is completely open source and free to edit on GitHub. You can see the GitHub page for this site at https://github.com/EphemeralSpace/docs.

Keep in mind that while web-edit PRs (those made through the GitHub web UI) are not allowed on the main Ephemeral Space Repo, this is not the case here.

Style

Documentation should be written in a technical communications style. Effective technical communications are concise, precise, direct, and well organized and should be written in an appropriate voice and tone using correct mechanics and grammar, citing relevant sources where needed.

Making basic edits

If you just want to make a basic edit of a page, simply follow these steps--you don't need any of the fancy stuff talked about later:

  1. Create an account on GitHub, or log in if you already have one.

  2. Fork the EphemeralSpace/docs repo on GitHub.

editing-docs-create-fork.png

  1. Find the file corresponding to the page you want to edit on the documentation repository.

  2. Click the 'Edit this file' button at the top right of the file view.

editing-docs-edit-file.png

  1. Make your changes, then commit & create a pull request! We'll handle the rest.

Building

If you want to locally build the docs, the necessary dependencies are Rust and some binaries installed using cargo. It's recommended that you use cargo install or cargo quickinstall, as building can take a while.

From cargo, install:

  • mdbook
  • mdbook-admonish
  • mdbook-embedify
  • mdbook-emojicodes
  • mdbook-linkcheck
  • mdbook-mermaid
  • mdbook-template

Run mdbook serve to build and locally host the documentation from the book directory at localhost:3000.

Testing changes

If you've made a PR, the easiest way to test your changes, since they're just markdown, is to view them in GitHub's own markdown viewer in the Files changed tab. You can also use a local markdown previewer extension for something like VSCode.

If you want a slightly more authentic experience, every PR will have the Test mdBook Build & Upload Artifact action run, and you can download the built site like so:

Then, just unzip it and open index.html. Our custom CSS and stuff won't work super well but it'll look good enough.

For an authentic-authentic experience, just follow the build instructions above and run mdbook serve like normal.

Review

Maintainers will review pull requests for documentation for content and style. Maintainers understand that many contributors do not speak English as a native language and will be helpful with their review comments.

To help make best use of maintainers' review time, before submitting please:

  • Proofread your changes
  • Use a spell checker
  • Consider using grammar review tools like Grammarly