Documentation Style Guide

Status: Draft

Scope: Internal documentation (Nova Help Cards). Does not cover public-facing content or API docs. Context: Slack discussion

This guide covers the writing style for internal docs (incl. Nova Help Cards).

For Markdown formatting, see markdown-formatting-guide.md. For Nova terminology, see nova-help-cards-guide.md.

Table of Contents

• Table of Contents
• Tone
  • Avoid "Please" and "You Can"
  • Avoid "Please Note"
• Simplify Language
  • Remove Filler Words
  • Avoid Redundancy
• Use Meaningful Link Text
• Be Specific
  • Avoid Vague Terms
• Use Active Voice
• Clarify Outcomes
• Consistent Warnings
• Consistent Structure
  • Field Formatting

Tone

Use a direct, professional tone. Write instructions as clear commands.

Avoid "Please" and "You Can"

<!-- Bad -->
Please make sure each Skill is associated with relevant Courses.
Here you can create Stories that will become part of the Timeline.
You can refer to the documentation for more details.

<!-- Good -->
Ensure each Skill is associated with relevant Courses.
Create Stories that will become part of the Timeline.
See the documentation for details.

Avoid "Please Note"

<!-- Bad -->
Please note that the Lens option is used by the dev team for debugging.

<!-- Good -->
The Lens option is used by the dev team for debugging.

Simplify Language

Remove Filler Words

Wordy	Better
in order to	to
make sure to	ensure
if you want to	to
at a glance	(remove)
simply click	click
you can simply	(remove)

Avoid Redundancy

<!-- Bad -->
Make sure you go through these steps to make sure everything is in order.
If you want to change their status, i.e. to unsubscribe them, click the edit button.

<!-- Good -->
Follow these verification steps.
To unsubscribe, click the edit button.

Use Meaningful Link Text

Never use "here", "this", or "click here" as link text. Use descriptive names.

<!-- Bad -->
You can find it [here](/admin/nova/resources/teams/70).
For details, see [this document](https://dropbox.com/...).

<!-- Good -->
See the [IxDF Design League Coaches](/admin/nova/resources/teams/70) team page.
For details, see [IxDF Manual - Internal Work Processes](https://dropbox.com/...).

Be Specific

Avoid Vague Terms

Vague	Specific
various fields	name, email, and status fields
necessary details	Master Class and Attendee fields
etc.	(list all items or remove)
and more	(list all items or remove)
some options	(name the options)
for further info	for field descriptions

<!-- Bad -->
Fill out the necessary details and other relevant information.

<!-- Good -->
Fill in the Master Class and Attendee fields.

Use Active Voice

Write what the system does, not what "is done."

<!-- Bad -->
If the transaction was initiated by a member, then `x` is displayed.
The fields can be changed by clicking the edit icon.

<!-- Good -->
Displays `x` for member-initiated transactions.
Click the edit icon to change fields.

Clarify Outcomes

Every instruction should state what happens next.

<!-- Bad -->
Click the blue edit icon.

<!-- Good -->
Click the edit icon to open the edit form.

<!-- Bad -->
Upload a hero image for each Story.

<!-- Good -->
Upload a hero image for each Story. The image appears at the top of the Timeline entry.

Consistent Warnings

Use a clear hierarchy for warnings and notes.

Level	When to Use	Format
Important	Critical steps that can cause data loss or errors	**Important:** text
Note	Helpful context, not critical	**Note:** text

<!-- Bad -->
IMPORTANT: If you update a template, you must regenerate the zip file.
Note: this step must be completed before proceeding.

<!-- Good -->
**Important:** Regenerate the zip file after updating a template.
**Note:** Complete this step before proceeding.

Avoid overusing warnings. If everything is "important," nothing is.

Consistent Structure

All help cards should follow this structure:

1. Overview - One sentence explaining the Resource
2. Key information - What staff need to know
3. Instructions - Step-by-step actions (if applicable)
4. Warnings - Important notes (if applicable)

Field Formatting

Use consistent formatting for field names:

<!-- Recommended -->
**Status** - Current state of the Resource
**Created At** - When the Resource was created