Nova Help Cards Writing Guide

Status: Draft

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

This guide covers content guidelines for writing Nova help cards. See also:

• style.md - Writing style (tone, clarity, simplicity)
• markdown-formatting-guide.md - Markdown formatting rules

Table of Contents

• Table of Contents
• Help Card Types
• Use Nova Terminology, Not UI Design Terms
  • Nova Core Terms
  • Nova Page Types
  • How to Describe Actions
  • More Examples
• Use Relative URLs for Internal Links
• Prefer "Search by X" Over Field Instructions
• Reference Nova Pages Consistently

Help Card Types

There are two types of Help cards on Nova:

Type	Location	Purpose
Index Help Card	Resource Index page	Explains the Resource list, available Filters (when needed), workflows
Details Help Card	Resource Details page	Explains Fields, available Actions, and how to edit a Resource

Use Nova Terminology, Not UI Design Terms

Documentation should use core Nova terms, not UI-specific descriptions like "icon", "3 dots", or "pencil". Why?

• Developers may change the UI anytime - documentation should remain valid.
• Shorter and more professional

Nova Core Terms

Term	Meaning
Resource	A data entity (Member, Order, Invoice, Coach, etc.)
Action	An operation you can run on a Resource
Filter	Criteria to narrow down the Resource list
Field	A data attribute of a Resource

Nova Page Types

Page	Purpose	Example URL
Index	List of Resources	/admin/nova/resources/members
Details (or View)	Read-only view of a single Resource	/admin/nova/resources/members/123
Edit	Form to modify a Resource	/admin/nova/resources/members/123/edit
Create	Form to add a new Resource	/admin/nova/resources/members/new

How to Describe Actions

<!-- Bad - UI-specific, fragile -->
Click the eye icon to view details
Click the pencil icon to edit
Click the 3 dots and select "Mark as paid"
Enter email in the Search field
Click the ID to open the record

<!-- Good - Nova terminology, stable -->
Open Member Details page
Open Edit Member page
Run "Mark as paid" Action
Search by email
Open the Order Details page

More Examples

<!-- Bad -->
Use the trash can icon available on the right-hand side

<!-- Good -->
Delete the Resource using Nova's delete/trash button

<!-- Bad -->
Click directly on any question to access its details

<!-- Good -->
Open the Question Details page

<!-- Bad -->
Use the pen icon available on the right-hand side of each Meetup

<!-- Good -->
Open the Edit Meetup page

Use Relative URLs for Internal Links

Use relative URLs for links to Nova pages and IxDF site. Help cards are rendered on different environments (production, staging), so absolute URLs will break.

<!-- Bad -->
[Members](/admin/nova/resources/members)
[IxDF Design League Coaches](https://ixdf.org/admin/nova/resources/teams/70)
[Join page](https://www.interaction-design.org/join)

<!-- Good -->
[Members](/admin/nova/resources/members)
[IxDF Design League Coaches](/admin/nova/resources/teams/70)
[Join page](/join)

Note: External links (Dropbox, Slack, etc.) should remain absolute.

Prefer "Search by X" Over Field Instructions

<!-- Bad -->
Enter the member's email address into the Search field and press Enter

<!-- Good, assume a reader knows basic UI elements and terms -->
Search Member by email address

BTW: Devs can customize which fields are searchable for every Resource, feel free to ask to change that list, it's easy!

Reference Nova Pages Consistently

<!-- Recommended patterns -->
Open the [Members Index](/admin/nova/resources/members) page
Navigate to the Member Details page
Run the "Impersonate" Action
Apply the "Active" Filter