Creating and Publishing Help Documentation

Creating effective help documentation in the Online Help Module involves understanding Page Key relationships, utilizing rich content creation tools, and implementing appropriate publishing workflows that ensure users receive accurate, accessible help information exactly when and where they need it.

Requirements

To create and edit Online Help documentation, users must be assigned a security role with the following permissions:

• All Entities, Help (system): Read, Create, Edit, Delete
• All Entities, Help Category (system): Read, Create, Edit, Delete

Understanding Page Key Architecture

Page Key Identification and Usage

Page Key Discovery: When administrators or Employee users with appropriate permissions click "Help on this page" for a portal page that doesn't have existing help documentation, they see a Page Key identifier that uniquely links help content to that specific portal location.

One-to-One Relationship: Each Page Key creates an exclusive relationship between a portal page and a help article. Help articles cannot be shared between multiple pages, ensuring contextual accuracy and preventing content confusion.

Permanent Page Linking: Once a help article is linked to a Page Key, it cannot be unlinked or reassigned to a different page. The article can only be edited, deleted, or replaced, but the Page Key relationship remains permanent.

Page Key Workflow Process

Step 1: Page Key Identification

1. Navigate to the portal page where you want to create help documentation
2. Click the "Help on this page" link
3. If no help exists, note the Page Key displayed on the 404 error page
4. Copy the Page Key for use in content creation

Step 2: Help Article Creation

1. Use the Page Key to create new help content through the Online Help management interface
2. Link the content directly to the identified Page Key
3. Develop appropriate help content for the specific page context

Creating Help Documentation

Accessing Help Content Creation

Method 1: Direct Page Creation

1. Navigate to the portal page needing documentation
2. Click "Help on this page" link
3. If you have create permissions and no help exists, click "Create New Help Page" or use the displayed Page Key
4. Complete the help page creation form

Method 2: Help Management Interface

1. Navigate to Setup Home > Online Help (or /sys/help)
2. Click "Add a New Page" or "New Help Page"
3. Enter the Page Key in the appropriate field
4. Configure help article settings and content

Help Article Configuration

Subject Field: Enter a descriptive title that clearly indicates the help topic and aligns with the portal page functionality. The subject serves as the article heading and search result title.

Page Key Field: Enter the exact Page Key copied from the portal page to establish the contextual relationship between help content and portal functionality.

Content Creation Interface: Use the rich text editor to develop comprehensive help content that addresses user needs and provides actionable guidance for portal functionality.

Rich Content Development

Advanced Text Editor Capabilities:

• Formatting Tools: Bold, italic, underline, strikethrough, font styles, sizes, and colors
• Structural Elements: Headers, lists, alignment, indentation, and spacing
• Interactive Elements: Tables, links, special characters, and navigation anchors

Rich Media Integration:

• Image Upload: Add screenshots, diagrams, and visual aids directly from computer or Magentrix server assets
• Video Integration: Embed instructional videos, demonstrations, and multimedia content
• Document Attachments: Link to related documents, forms, and resources

Content Organization Features:

• Headers and Subheaders: Create scannable content with logical information hierarchy
• Lists and Bullets: Organize procedural steps and key information for easy reading
• Tables: Present complex information in structured, comparable formats

Help Category Management

Creating and Organizing Categories

Creating Top-Level Categories:

1. In the Online Help management interface, locate the Content Hierarchy & Categorization section
2. Click "New Top-Level Category"
3. Enter a descriptive category name that represents a major help topic area
4. Click Save to create the category

Creating Subcategories:

1. Right-click on an existing category in the hierarchy
2. Select "Add Sub-Category" from the context menu
3. Enter a descriptive subcategory name
4. Click Save to add the subcategory

Multi-Level Category Nesting: The help system supports unlimited category nesting levels, enabling complex content organization that can scale with organizational needs and content complexity.

Category Management Best Practices

Logical Information Architecture: Organize categories based on user workflow patterns and business process logic rather than system architecture, ensuring users can find information using natural navigation patterns.

Consistent Naming Conventions: Use clear, consistent naming that reflects user language and organizational terminology, avoiding technical jargon that might confuse end users.

Content Grouping Strategy: Group related help topics together to support user discovery patterns and enable efficient browsing of related information and procedures.

Content Creation Workflows

Draft and Publishing Process

Creating Draft Content:

1. Begin content creation in draft status to allow for development, review, and refinement without making content publicly visible
2. Use draft status for collaborative content development and quality assurance processes
3. Draft content is only visible to users with appropriate edit permissions

Content Review and Quality Assurance:

• Review content for accuracy, completeness, and alignment with organizational standards
• Verify that screenshots and media content are current and accurate
• Test procedural instructions to ensure they work as documented
• Check links and cross-references for accuracy and functionality

Publishing Content:

1. When content is ready for user access, click "Publish" to make the help article publicly available
2. Published content immediately becomes visible to users through contextual help links and help portal browsing
3. Published content can be edited and updated without changing publication status

Content Lifecycle Management

Version Control and Updates:

• The help system maintains content history and enables updates without losing previous versions
• Content creators can make updates to published content that take effect immediately
• Track content changes and maintain audit trails for content modifications

Content Maintenance Procedures:

• Establish regular review cycles to ensure help content remains current with system changes
• Update screenshots and procedural instructions when portal functionality evolves
• Monitor user feedback and help system usage to identify content improvement opportunities

Advanced Content Features

Interactive Content Development

Cross-Reference Integration: Create links between related help articles to support comprehensive user learning and enable exploration of connected topics and advanced functionality.

Anchor Navigation: Use anchor links within long help articles to enable users to jump directly to specific sections, improving usability for comprehensive documentation.

Media Enhancement: Incorporate screenshots, annotated images, and instructional videos that provide visual context and enhance understanding of complex procedures.

Content Optimization

Search Engine Optimization: Use descriptive titles, headers, and content structure that support effective search functionality within the help system.

Mobile Responsiveness: Ensure content displays effectively across different devices and screen sizes by testing formatting and media display on various platforms.

Accessibility Considerations: Structure content with proper heading hierarchy, descriptive link text, and alternative text for images to support users with diverse accessibility needs.

Publishing Strategies

Content Publication Planning

Immediate Publication Strategy: For organizations requiring real-time help updates, publish content immediately upon completion to ensure users have access to current information.

Staged Publication Approach: For organizations with quality control requirements, use draft status for content development and coordinate publication timing with system updates and user communication.

Content Rollout Coordination: Align help content publication with feature releases, system updates, and user training initiatives to maximize content effectiveness and user adoption.

Quality Assurance Integration

Review Workflows: Implement organizational processes for content review and approval even when technical permissions allow direct publishing by content creators.

Content Standards: Establish organizational standards for help content including writing style, formatting consistency, and information completeness.

User Testing: Conduct user testing of help content to ensure clarity, accuracy, and effectiveness before widespread publication and use.

Best Practices for Effective Help Content

Content Development Strategy

User-Centered Approach: Focus help content on actual user tasks, common questions, and workflow patterns rather than system features, ensuring documentation provides practical value.

Task-Oriented Writing: Structure help content around user goals and tasks rather than system functions, enabling users to find relevant information based on what they want to accomplish.

Progressive Information Disclosure: Present information in logical sequences that build from basic to advanced concepts, supporting users with different experience levels.

Writing and Formatting Standards

Clear, Concise Language: Use straightforward language with consistent terminology and avoid unnecessary technical jargon that might confuse users.

Scannable Content Structure: Use headers, bullet points, and white space effectively to create content that users can quickly scan and navigate.

Actionable Instructions: Provide specific, step-by-step instructions with clear expected outcomes so users know they are following procedures correctly.

Content Maintenance Excellence

Regular Content Audits: Establish schedules for reviewing content accuracy and relevance based on system changes, user feedback, and content performance metrics.

User Feedback Integration: Monitor help system usage patterns, search queries, and user behavior to identify content gaps and improvement opportunities.

Continuous Improvement: Use analytics and user feedback to refine content organization, improve clarity, and enhance user experience over time.

Common Content Creation Scenarios

New Feature Documentation

Feature Release Coordination: Create help documentation in coordination with new feature releases, ensuring users have immediate access to guidance when new functionality becomes available.

Comprehensive Coverage: Document not only how to use new features but also when to use them, why they are beneficial, and how they integrate with existing workflows.

User Adoption Support: Create content that supports user adoption by addressing common concerns, highlighting benefits, and providing practical implementation examples.

Process Documentation

End-to-End Workflow Coverage: Document complete business processes that may span multiple portal areas, providing users with comprehensive guidance for complex tasks.

Role-Specific Instructions: Create content tailored to specific user roles and responsibilities, ensuring users receive relevant information that supports their job functions.

Exception Handling: Include troubleshooting information and guidance for handling unusual situations or system issues that users might encounter.

Troubleshooting and Self-Service

Problem-Solution Format: Structure troubleshooting content in clear problem-solution format that helps users quickly identify their situation and find appropriate solutions.

Escalation Guidance: Provide clear information about when and how to escalate issues that cannot be resolved through self-service documentation.

Preventive Information: Include best practices and preventive guidance that helps users avoid common problems and use the system more effectively.

Troubleshooting Content Creation Issues

Common Publishing Problems

Page Key Not Displaying: If Page Key is not visible when clicking help links, verify that the user has Create permissions for Help (system) entity. Users with only Read permissions will see 404 errors instead of Page Keys.

Content Not Appearing: If published help content is not visible to users, verify that the Page Key was entered correctly and that users have appropriate Read permissions for Help (system) entity.

Category Organization Issues: If categories are not displaying correctly, verify Help Category (system) permissions and check that category hierarchy was saved properly.

Content Quality Issues

Formatting Problems: If content formatting is not displaying correctly, review rich text editor usage and ensure media files are accessible to target users.

Link Functionality: If internal links or cross-references are not working, verify that linked content is published and accessible to users with appropriate permissions.

Search Discoverability: If help content is not appearing in search results, review content titles, headers, and text content for relevant keywords and search terms.

Integration with Content Strategy

Organizational Content Standards

Brand Consistency: Ensure help content aligns with organizational brand voice, terminology, and visual identity standards for professional user experience.

Content Governance: Implement governance processes that maintain content quality, accuracy, and consistency across all help documentation.

Cross-Module Consistency: Coordinate help content with other organizational documentation and training materials to provide consistent user experience and information.

Performance and Analytics

Usage Monitoring: Track help content usage patterns, popular articles, and user search behavior to optimize content development priorities.

Effectiveness Measurement: Measure help content effectiveness through user feedback, support ticket reduction, and user self-service success rates.

Continuous Optimization: Use performance data to identify content gaps, improve existing documentation, and enhance overall help system effectiveness.

Jump to Online Help Setup Checklist

<< Configuring Online Help Access and Permissions | Managing Help Categories and Content >>