Adding docs for new features

Use the following guidance to understand how we think about documenting a new Astro core or integration feature, including updates (e.g. new options, helper functions) for existing features.

Ultimately, our goal for the Astro Docs website is to document how to build with Astro and not how Astro is built.

What should be documented

In addition to providing a changeset message for your implementation PR, you must document any new option, configuration, or method that someone building a project with Astro might use.

Include a definition and/or short explanation, and a basic usage example, following our guide to including code samples.

The documentation should first define and then primarily answer questions about using a new feature:

• What is this?
• What is it used for?
• Why would I use it?
• In which situations can it (not) be used?
• How do I use it?

What should NOT be documented

Implementation details

Generally, you do not need to document implementation details. These do not often affect how someone uses the feature.

However, you may choose to include some of these details if they will help people understand and make decisions as they build their own projects:

• choose when to set a value other than a default
• avoid conflicting settings that do not produce the desired result
• understand the pros and cons or caveats of certain design decisions

But, implementation details should never be provided instead of usage details and real-world examples.

For example, if a reader must choose between setting a value to include or exclude, describe different situations or goals for which each option is best. Do not instead explain the underlying code logic that performs the inclusions and exclusions.

Non-traditional or unsupported use

You do not need to document all possible uses of your feature. You may include a common advanced case, but do not document usage that is unsupported or “off the happy path.”

You are not required to demonstrate all things possible, and in fact, too many options can overwhelm someone trying to learn how to use your feature.

“You can do this, but I wouldn’t recommend it…” is not something for docs! Don’t lead your reader down a dangerous path. They are free to explore themselves, and seek support for advanced or atypical use cases.

When to involve docs maintainers?

Whenever you are thinking about how the user will use the feature!

It can be useful to get docs maintainers involved when you’re considering the user experience of the feature. For example, if you are creating a new configuration option, docs maintainers can help you look at look at things from a (new) user perspective: Does the name accurately describe the user intention and what they are trying to achieve (and not what the underlying code or logic is doing, which might be quite different)?

In this way, docs maintainers can get involved earlier than you think… As soon as you know what the user story is!

Docs maintainers can also help you by being an early “user” of the process and surface unmet user expectations, friction, or even possible errors while using the feature.

For example, if your code’s logic filters out results in order to provide a list of items, but the user sees this as a way to include items on the page, there can be the potential for confusing naming. Even accurate names can still be problematic if they are prone to misspelling, easily mistyped, or too close to other similar names.

Docs maintainers can help identify a user’s thinking based on using the feature instead of caring about the underlying implementation of the feature.

Requesting a review from Docs

Team Docs reviews all text changes to the Astro documentation. Some exceptions include obvious typos and link fixes where no actual content changed. However, even a tiny change in wording of our documentation is reason to wait for a review from one of our Docs Maintainers.

Use the /ptal command in Discord in the #docs-ptal channel if you have access (Astro maintainers) or the regular #docs channel otherwise. We encourage posting requests for reviews publicly so that any interested community member can comment and provide helpful feedback!

For PRs not in the docs repo that require approval from a docs maintainer before merging, you can also mention the role @withastro/maintainers-docs in your PR. This will notify all Astro maintainers with the docs role.

Waiting for a review from Docs

Even a minor change in phrasing can change the nuance of a sentence. Docs would typically prefer to review these changes before merging, however small, unless they are truly fixes/corrections.

Additionally, the word or phrase you are changing may be used in other parts of the documentation as “standard wording” and a change here might mean updating other parts of the page or site. For example, you may be updating the way you describe the usage of one integration or adapter, but we might have a corresponding section or example for each one that should therefore also change.

The docs maintainers have a “big picture” awareness of the larger effects that a smaller change may have throughout the rest of the documentation, and work to ensure consistency across the entire site.

Getting a Docs approval

It is very common for several people to review docs PRs, and not all approvals mean that your PR can be merged.

Team Docs encourages our community members to review PRs to catch small problems before docs maintainers edit larger contributions, or even to practice their own reviewing skills!

All new feature documentation must be approved by the Docs Lead personally before the PR is considered ready to merge.

Merging your own PRs as a maintainer

Astro maintainers are welcome to merge their own PRs in either repo (astro or docs) after appropriate docs approval for small updates and fixes that can be published to docs immediately (i.e. they do not document an upcoming, unreleased feature).

There is a nightly GitHub action to create a PR to the docs repo with any documentation changes from the core repo. These docs changes will therefore typically be published on the docs site the next day after merging. This action can also be run manually to expedite the process, as is regularly done for major and minor releases.

Docs for upcoming features

Unlike PRs to the astro repo, PRs to the docs repo are published live immediately upon merging. Therefore, the docs repo labels upcoming feature docs with merge on release and waits for a feature to released before merging approved PRs.

Minor releases happen every other Thursday for the astro core package itself and the Docs Lead prepares and merges these docs on that regular schedule. Even as a maintainer, you will not merge these PRs yourself.

Other packages, such as integrations, only release when necessary. These merge on release docs are released alongside the package as appropriate and may be merged by any maintainer after they are approved and the feature has been released.