If you see something off with Mixpanel's docs (typo, broken link, outdated content/screenshot) you can contribute that fix yourself!
You’ll need a GitHub account. It’s free and takes 1 minute to create. Not sure what to make your handle? We recommend yourfullname-mixpanel.
To make an edit:
- Go to the page in our documentation that you want to edit. On the right side, under the table of contents, you should see an "Edit This Page" link. That will take you to the file in Github that contains the contents of that doc.
- Click the pencil icon to make edits to a file’s markdown. You can swap between code and preview to see what your edits look like.
- When you’re ready, hit “Commit” and follow the instructions to commit the changes to your branch and create a pull request review. Add a description if you like, keeping in mind that this is publicly accessible.
- If you're making multiple related changes, don't create a pull request right away. Continue making changes in the branch until you're ready to post all of the changes together in one PR
- One of the docs maintainers will review that request within 3 days and merge when approved (usually faster if it’s a small change).
- Once merged, changes will go live automatically, typically within 1-2 minutes.
This is a bit more advanced, but makes it much faster to test the impact of your changes (no waiting for the staging deployment):
- Clone the repo
- Install dependencies:
npm ci
- Run the following to start serving the docs at http://localhost:3000
npm run dev
- Make whatever changes you want locally, this should automatically reflect in your local instance of the docs.
We use CSpell to automate spell checking. With the npm dependencies installed, use the following to check pages for spelling:
npm run spelling
If you are using VSCode, we recommend you install streetsidesoftware.code-spell-checker to automate fixing spelling errors.
Add words to the dictionary and otherwise configure the spell checker using cspell.json.
For more advanced usage, you can use the underlying cspell tool like so:
npx cspell --help
Upload images/GIFs to the public/ directory. You can make sub-directories within public/ to namespace them (eg: /public/tutorials/ for all tutorial-related images).
To reference an image, use a relative link to the image with the public stripped out. For example, if you have an image public/example.png, you can reference it as follows: [insert alt text here](/example.png). Ensure that the the image filename has no spaces and are separated by either a hyphen or an underscore.
If you're making a diagram, please add it to this Figjam. That way, if others want to make small tweaks, they can discover the original.
Images are hard to keep up-to-date, so please use them judiciously.
All pull requests will generate a staging link in Vercel. Here's an example. This lets you preview your changes without changing what's actually live.
You may also preview changes by testing locally
We are now using Nextra 3, which is slightly different than Nextra 2. The main differences for most maintainers is that instead of _meta.json to generate custom sidebars, it is now in Javascript or Typescript, and can be rendered with components. Another difference is that Tab is now imported from Tabs.Tab and Card from Cards.Card, both from nextra/components.
We make a changelog post for every feature we ship. It usually includes a Loom link + a description of the feature. Make sure to include either video: <loom link> or thumbnail: <image> to ensure that we have a preview video or image for every changelog post.
Here is an example that you can clone to add a new changelog post.
Marissa, Mav, Isha, and Myron. Eventually we’ll expand this list, but keeping it tight for now.
For simple content changes, the reviewer will merge the PR for expediency. For code changes, the original author will merge changes.
To make changes to developer docs, search internal documentation for "developer.mixpanel.com" or inquire in the #docs chat channel.