docs: Add Gamut writing guide

[LinKCoding]

Overview

Adds a style guide for documentation purposes

PR Checklist

• Related to designs:
• Related to JIRA ticket: GMT-157
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions tests for the code change
• The alpha package of this PR is passing end-to-end tests in all relevant Codecademy repositories

Testing Instructions

Don't make me tap the sign.

1. Go to story /?path=/docs/meta-style-guide-about--docs
2. Check that the links work
3. Go through the pages and check that guidelines make sense
4. ...
5. Finish and do a celebratory dance

PR Links and Envs

N/A

[nx-cloud]

View your CI Pipeline Execution ↗ for commit dbb5e09

---

☁️ Nx Cloud last updated this comment at 2025-12-09 18:55:55 UTC

[aresnik11]

Some initial thoughts!

[dreamwasp]

lgtm, def want emily to take a look!

[sh0ji]

Finally had a chance to get my thoughts down, and there are a lot of them but I'm generally very excited about this. Great job on it!

Two other, more meta questions:

1. Should this guide live in Storybook? If it's for people writing Gamut documentation, my inclination is that it should be part of a contribution guide rather than part of Gamut docs.
2. How do we want to this guide to relate to Codecademy styling and grammar? Should our guide be aware of it? In deference to it? The draft you've written doesn't currently seem to acknowledge it and even conflicts with it in a few places (I only noted one).

[sh0ji]

I much prefer "we" in any writing where the reader is learning from an expert because it quietly invites the reader to be the expert, whereas "you" creates a line between author and reader: "I the expert am telling you the novice what's what." Or more simply, "we" is inclusive, "you" creates separation.

My general advice here is to prefer "we" whenever possible because there will be times when "you" is the better choice. For instance, it wouldn't make sense to say "use our best judgment" if we're encouraging the reader to use their judgment, so "use your best judgment" would be fine. But those instances are surprisingly rare—we can usually use "we" for most things without much effort.

[uxemilylee]

For product copy/UX writing we :) generally use "we" as the voice of the company, and we use "you" for a more conversational tone with learners.

I can understand this sentiment of being inclusive for this context of documentation. One question: I remember seeing a reference to being explicit about "we" as Codecademy where applicable (can't seem to find it right now)... would we want to place that piece of information closer to this, since Gamut is public and referred to from some of our courses?

[sh0ji]

Our users are primarily (entirely?) other Skillsoft employees, which is one reason we might want this to be different from company style.

As an aside, this was a very specific style point that was used to great effect at Norton. When we switched to using "we" in our composition list in particular, we saw huge growth (it was accompanied by lots of other changes, but this one was notable to our editor). Instead of an expert telling you—the learner—how to write, we were writing together.

[LinKCoding]

Seems like we can take this in different directions —

1. where we explicitly call out when to use "we" (maybe add this in as part of line 18)
2. removing/rewriting line 19 to emphasize "we" more

I think it seems to lean more towards point 1, where we call out the usage of "we" (there is also a separate section in "Language and Grammar" that touches upon this.

Will note that we should discuss as a group

[sh0ji]

Let's not include user space technology choices in our guidelines. If anything, we should recommend documentation writers be inclusive about the technology choices of our users.

# install with your package manager of choice
npm install @codecademy/gamut-kit
pnpm add @codecademy/gamut-kit
yarn add @codecademy/gamut-kit

Or better yet, let the user choose their package manager globally and then just show commands for it.
For instance, this is what I did for the Norton Design System's getting started guide (source code).

[LinKCoding]

This seems more inline with the Installation guide we have up, but I can't seem to find the ticket rn, will revisit

[sh0ji]

Another thought: a lot of this guidance would be very useful in an agent instructions/rules/skills file. I often have Cursor help me write docs, and it always seems to format things in ways I don't like, so I end up having to correct it. This guide would be a huge help with that.

For instance:

• ./.cursor/rules/documentation-style.mdc - for Cursor
• ./.github/instructions/documentation-style.instructions.md - for GitHub Copilot & VSCode
• ./CLAUDE.md - for Claude, which just allows for the one file
  • I think Skills would be something like ./skills/documentation/{SKILL,STYLE}.md, where the SKILL.md "imports" the STYLE.md file, but I haven't used that yet.

[dreamwasp]

have the tiniest comments but this looks great to me

[dreamwasp]

we usually will do a folder name in addition to a file name for components

[codecademydev]

📬 Published Alpha Packages:

@codecademy/[email protected]

[github-actions]

🚀 Styleguide deploy preview ready!

Preview URL: https://6938717c28c0af1a5315f7d7--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/6938717c28c0af1a5315f7d7