Content Writing Best Practices

1. Organizing Your Help Content

Use Clear Button Groups:

• Getting Started - Basic tasks and first-time user guidance
• Navigation - Moving around the application
• Data Entry - Forms, fields, and data input
• Reports - Generating and viewing reports
• Advanced Features - Power user functionality
• Troubleshooting - Common problems and solutions

Example Menu Structure:

Help Menu:
├── Getting Started
│   ├── Creating Your First Subject
│   ├── Understanding Projects
│   └── Basic Navigation
├── Data Entry
│   ├── Subject Information
│   ├── Encounter Data
│   └── Required vs Optional Fields
└── Advanced Features
    ├── Bulk Operations
    ├── Custom Reports
    └── Data Export

2. Writing Effective Help Content

Keep It Focused:

• One topic per help page
• Start with the most important information
• Use clear, simple language
• Include step-by-step instructions when appropriate

Use Helpful Formatting:

• Bold important terms and button names
• Use numbered lists for procedures
• Use bullet points for options or features
• Include screenshots when helpful

Good Example:

# How to Create a New Subject

1. Click the **Add Subject** button on the Home page
2. Fill in the required fields:
   • **Study ID** - Must be unique within the project
   • **Date of Birth** - Use MM/DD/YYYY format
   • **Site** - Select from the dropdown menu
3. Click **Save** to create the subject

3. Field-Level Help Guidelines

Keep It Short:

• 1-2 sentences maximum
• Focus on format requirements or examples
• Explain why the field is important if not obvious

Good Field Help Examples:

• Study ID: “Unique identifier for this subject. Format: STU-001”
• Date of Birth: “Required for age calculations. Use MM/DD/YYYY format.”
• Phone: “Include area code. Format: (555) 123-4567”

4. Testing Your Help Pages

Check Your Work:

1. Refresh help data - Click the HELP menu item to go to the Help Center, then click the “Refresh Help” button to load your changes from Notion
2. Navigate to the application page where your help should appear
3. Look for your help button in the toolbar
4. Click the button and verify your content appears in the right section
5. For field help, look for help icons next to the specified fields
6. Test that your content opens and displays correctly

Important: Always refresh help data after making changes in Notion before testing your updates.

Common Content Issues to Avoid

❌ Don’t Create Orphaned Content

Problem: Help page doesn’t appear anywhere Solution: Always set the page property to specify where help should appear

❌ Don’t Forget to Set pageType for Menus