Writing Name Change Guides

Namesake organizes its information into guides. Each guide is written to direct someone, step-by-step, through the process of updating their name and/or gender marker with a specific institution.

Before you write anything, conduct research to help understand the name change landscape.

Conducting ResearchHere's how to run a successful interview and learn more about the ins-and-outs of the name change process for a particular state.

Organization

Guides are created in web/src/content/guides using .mdx files which contain:

Frontmatter (metadata about the guide, including its title and description)
Markdown (plain text with specific syntax for things like **bold** and _italics_)
Components (.astro and .tsx files with more complex behavior, for things like tables and embedded forms)

Keep urls organized and easy to type

State-specific guides should be nested under a two-letter directory containing the state abbreviation, such as ma or ri. Guides which are not specific to a state can be placed directly within /guides.

Directoryweb/src/content/guides
- Directoryma Massachusetts
  - birth-certificate.mdx
  - court-order.mdx
  - state-id.mdx
- Directoryri Rhode Island
  - birth-certificate.mdx
  - court-order.mdx
  - state-id.mdx
- passport.mdx
- social-security.mdx
- …

Filenames should use kebab-case and be easy to type.

When URLs are renamed, existing links to Namesake will break, causing link rot. Avoid renaming files within src/content and src/pages, since these filenames are used to generate site URLs.

If renaming is unavoidable, add an entry to redirects in astro.config.ts:

export default defineConfig({
  redirects: {
    '/old-url': '/new-url',
    '/guides/old-name': '/guides/new-name',
  },
});

Break the guide into key sections

Short, descriptive section headers help the user orient themselves on the page and within the process. You should be able to scan the headings of any guide and understand the overall “shape” of the steps required.

Aim for fewer than 7 main sections. The typical human can store about 7 items in working memory. Beyond that, things can begin to feel overwhelming. Keep it focused. If more content divisions are needed, consider using nested sub-sections.
Use level-two headings. The page title is the first-level heading of the document, which means that the “top” headings within a guide should begin with ##. Headings may be nested 1-2 levels deeper (h3 ### and h4 ####) when needed.
Keep headings short. Headings display in the sidebar and should be kept short and descriptive.
Use active voice. Start headings with a verb, e.g. “Get prepared”, “Fill out forms”.
Write from the perspective of the user. (Think of it like completing the sentence: “In order to get through this step, I need to _____.”)

List prerequisites upfront

The very first thing in a guide should be a list of the documents and steps that are required to file.

For example:

## Get prepared

To file, you will need:

1. A certified copy of your birth certificate (long-form). This is available from the Registry of Vital Records or from the city or town where you were born.
2. Past name change documents, if applicable. For example, a marriage certificate or Judgment of Divorce.

Common prerequisites include a completed court order, updated social security, and updated ID. When this is the case, link to existing Namesake guides for these requirements.

Don’t hide important info behind external links

A Namesake guide should be self-contained, allowing a reader to understand the process without navigating to other webpages. Put the information inline, and link to the source for readers who want to verify details.

Collapse non-essential details

There are questions about the name change process which are important to answer but may not apply to the majority of readers. Answer these questions without making the page look long and intimidating by hiding them behind a toggle.

Use the <details> element to collapse non-essential information. For example:

<details>
  <summary>What if my birth certificate is not written in English?</summary>

  Birth certificates that are not written in English must include a written translation signed by the person translating the birth certificate with a statement that they are fluent in the foreign language and English and that the translation is a true and accurate translation. The translators signature must be notarized.

</details>

<details> elements should be placed after the main content of a section.

Embed interactive forms

Namesake uses guided forms to help users fill out PDFs. Forms which are relevant to a particular guide should be displayed inline by importing FormContainer:

import { FormContainer } from "#components/forms/FormContainer/index.ts"

Formcontainer accepts a slug and should be set to client:load and inline for proper rendering within guides:

## Fill out forms

<FormContainer client:load slug="court-order-ma" inline />

Display maps beside addresses

When an address is displayed, import the MapEmbed component:

import MapEmbed from "#components/MapEmbed.astro"

The component accepts a name string and address object.

Bring all documents to the Center for Vital Records:

<MapEmbed
  name="Rhode Island Department of Health Center for Vital Records"
  address={{
    address1: "Simpson Hall",
    address2: "6 Harrington Road",
    city: "Cranston",
    state: "Rhode Island",
    zip: "02920"
  }}
/>

The name is used to query Google Maps and display an <iframe> alongside the address itself. See an example.

Mark incomplete guides as “stubs”

If a guide is incomplete or lacks important information, mark it as a stub in the frontmatter.

title: Court Order
description: This is an incomplete guide!
stub: true

Stubbed guides include a banner at the top. Links to stubbed guides display in red text.

Cite your sources

Add a “References” section at the botom of each guide. Within it, cite any sources that were used to supply info for the guide. Use this simple citation format:

## References

- Author name or government agency name. [Page title](https://example.com).

For example:

## References

- Massachusetts Registry of Vital Records and Statistics. [Amend a birth certificate for sex of the subject](https://www.mass.gov/how-to/amend-a-birth-certificate-for-sex-of-the-subject).

Writing

Do not use AI

It is critical that Namesake provides information that is accurate and reliable. Never use ChatGPT, Claude, or other AI tools to generate guides.

These tools hallucinate wrong but plausible-sounding information. Do not trust them.

It is our responsibility to research and share vetted information about the name change process, and that’s a responsibility we take very seriously.

Use plain language

All readers can benefit from clear, straightforward writing, but this can be particularly important for people who:

are reading in a non-native language
are frustrated, tired, or in a hurry
have cognitive, learning, or attention difficulties
do not have familiarity with the legal system

Aim for clear and helpful documentation that serves the reader above all else.

Usually this means choosing:

shorter sentences and paragraphs
simpler vocabulary and phrases
less jargon
fewer assumptions about what the reader already knows
bullet points and section headings to break up chunks of text

For more information, read plainlanguage.gov.

Write out abbreviations and acronyms

The first time you use an abbreviation or acronym, write it out in full.

✅ Mail your documents to the Rhode Island Bureau of Criminal Investigation (BCI).

❌ Mail your documents to BCI.

Use descriptive links

When linking to external resources, use descriptive text that clearly indicates what the link is for. Avoid generic phrases like “click here” or “learn more”.

✅ Get a certified copy of your birth certificate from the Registry of Vital Records.

❌ Get a certified copy of your birth certificate here.

Celebrate success and link to next steps

The breaucratic process can feel cold and impersonal; it’s important for Namesake to bring some humanity back into this process. At the end of each guide, congratulate the user for a job well-done! Provide links to recommended next steps.