diff --git a/docs/README.md b/docs/README.md index dea5f88dc70..e2ed72ed35e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,24 +5,10 @@

Bun Documentation

-Official documentation for Bun: the fast, all-in-one JavaScript runtime. - -## Development - -Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview the documentation locally: - -```bash -bun install -g mint -``` - -Run the development server: - -```bash -mint dev -``` - -The site is served at `http://localhost:3000`. +Official documentation for Bun: the fast, all-in-one JavaScript runtime. [bun.com/docs](https://bun.com/docs) is built from the files in this directory. ## Contributing Contributions are welcome. Open an issue or submit a pull request. + +Before writing or editing a page, read the [voice guidelines](https://bun.com/docs/project/contributing#voice) (source: `project/contributing.mdx`): short sentences, active voice, present tense, second person, and no "easy", "simple", or "just". diff --git a/docs/project/contributing.mdx b/docs/project/contributing.mdx index daefc25cf17..1db37cf3483 100644 --- a/docs/project/contributing.mdx +++ b/docs/project/contributing.mdx @@ -377,3 +377,23 @@ The built version of Bun may not work on other systems if compiled this way. - Disable logging: `BUN_DEBUG_QUIET_LOGS=1 bun-debug ...` (to disable all debug logging) - Enable logging for a specific scope: `BUN_DEBUG_EventLoop=1 bun-debug ...` (to enable `scoped_log!(EventLoop, ...)` output) - Bun transpiles every file it runs. To see the actual executed source in a debug build, find it in `/tmp/bun-debug-src/...path/to/file`. For example, the transpiled version of `/home/bun/index.ts` is in `/tmp/bun-debug-src/home/bun/index.ts` + +## Contributing to the docs + +The docs are the MDX files in `docs/` in the Bun repository. [bun.com/docs](https://bun.com/docs) is built from them. + +### Voice + +A docs page describes what Bun does and what you can do with it. Write it so that a developer who is new to Bun can read the page once and act on it. These guidelines are adapted from the [Next.js docs contribution guide](https://nextjs.org/docs/community/contribution-guide#voice): + +- Write short sentences that each make one point. If a sentence needs several commas or a parenthetical, split it up or turn it into a list. +- Use plain words: "use" rather than "utilize", "to" rather than "in order to". Cut filler such as "Note that" and "Please". +- Use the active voice and name the actor: "Bun reads `bunfig.toml`", rather than "`bunfig.toml` is read". A sentence built around "is" and "by" is usually passive. +- Describe current behavior in the present tense: "Bun installs the package", rather than "Bun will install the package". +- Name the subject when "this" or "it" could refer to more than one thing: "`--isolate` is how Jest behaves by default", rather than "This is how Jest behaves by default". +- Address the reader as "you", and make Bun (or the specific tool) the other actor: "Bun caches the tarball", rather than "we cache the tarball" or "let's cache the tarball". +- Leave out "easy", "simple", "just", and "quick". They add nothing when a task is easy and discourage readers when it is not. State the concrete property instead: "one command", "no configuration". +- Say what to do rather than what to avoid: "use `port: 0` so the operating system picks a free port", rather than "don't hardcode ports". State limitations plainly; a limitation is a fact, not a warning to the reader. +- Use gender-neutral language: "developers", "users", "they". +- Make link text name its destination: "see [`bun install`](/pm/cli/install)", rather than "see here". +- Run every code example before you publish it, and check option names and defaults against the implementation on `main`.