Skip to main content

ThingConnect Pulse Documentation Guide

This guide helps contributors understand how to update and maintain the ThingConnect Pulse documentation.

Overview​

The Pulse documentation uses a dedicated Docusaurus plugin instance that serves content at /pulse/ with its own independent navigation and structure.

Documentation Architecture​

File Structure​

pulse/
├── CLAUDE.md              # This file - contributor guide
├── quick-start.md          # Installation and setup guide
├── yaml-configuration.md   # Configuration documentation
├── live-board-and-history.md  # Dashboard and data viewing
├── data-model.md           # Data structure reference
├── rollups-and-outages.md  # Analytics and reporting
├── installer-and-upgrade.md   # Installation/upgrade procedures
├── troubleshooting.md      # Common issues and solutions
└── api/
    └── overview.md         # API documentation overview

Landing Page​

The Pulse landing page is a React component located at:

  • File: src/pages/pulse/index.tsx
  • Styles: src/pages/pulse/pulse.module.css
  • URL: /pulse/

This React page serves as the product overview and entry point, while the documentation files in this folder provide detailed technical content.

The navigation structure is defined in pulse-sidebars.ts (project root):

const sidebars: SidebarsConfig = {
  pulseSidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'quick-start',
        'yaml-configuration',
        'installer-and-upgrade',
      ],
    },
    {
      type: 'category',
      label: 'User Guide',
      items: [
        'live-board-and-history',
        'data-model',
        'rollups-and-outages',
        'troubleshooting',
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      items: [
        'api/overview',
        // Auto-generated API docs can be added here
      ],
    },
  ],
};

Content Guidelines​

Markdown Files​

All documentation files use standard Markdown with frontmatter:

---
title: Page Title
sidebar_position: 1  # Optional: custom ordering
---

# Page Title

Your content here...

Writing Style​

  • Target audience: Technical users, system administrators, developers
  • Tone: Professional, clear, concise
  • Format: Step-by-step instructions where applicable
  • Code examples: Use proper syntax highlighting with language tags

Assets and Images​

  • Store images in /static/img/pulse/ directory
  • Reference images using: ![Description](/img/pulse/image-name.webp)
  • Use descriptive filenames and alt text for accessibility

Common Editing Tasks​

Adding a New Page​

  1. Create a new .md file in the pulse/ directory
  2. Add frontmatter with title and optional metadata
  3. Update pulse-sidebars.ts to include the new page in the navigation
  4. Test locally with npm start

Updating the Landing Page​

The React landing page (src/pages/pulse/index.tsx) contains:

  • Hero section with animated pulse visualization
  • Feature cards highlighting Pulse capabilities
  • Quick action cards linking to documentation sections
  • CTA section for downloads and support

To modify the landing page:

  1. Edit the React component in src/pages/pulse/index.tsx
  2. Update styles in src/pages/pulse/pulse.module.css
  3. Ensure all links point to valid documentation pages

Adding API Documentation​

  1. Create new files in pulse/api/ directory
  2. Update the API Reference section in pulse-sidebars.ts
  3. Consider using auto-generated docs for OpenAPI specifications

Development Workflow​

Testing Changes​

# Start development server
npm start

# Navigate to http://localhost:3000/pulse/
# Test all navigation links and page content

Building for Production​

# Build the site
npm run build

# Test production build
npm run serve
  • Internal links: Use relative paths (./other-page or ../api/overview)
  • Cross-product links: Use absolute paths (/docs/shared/authentication)
  • External links: Use full URLs with https://

File Naming Conventions​

  • Use kebab-case for filenames: yaml-configuration.md
  • Be descriptive but concise: installer-and-upgrade.md
  • Group related content in subdirectories: api/overview.md
  • Getting Started: Installation, basic setup, essential configuration
  • User Guide: Daily usage, features, troubleshooting
  • API Reference: Technical integration, endpoints, examples

Cross-Linking​

  • Link to related sections within Pulse docs
  • Reference shared documentation when appropriate
  • Provide "next steps" at the end of pages

Content Review Checklist​

Before submitting changes:

  • All links work correctly
  • Code examples are tested and accurate
  • Images display properly and have alt text
  • Navigation structure makes sense
  • Content follows writing style guidelines
  • No broken references to moved/deleted files

Getting Help​

Important Notes​

  • The Pulse documentation is independent from the main /docs/ section
  • Changes to pulse-sidebars.ts affect the entire Pulse navigation
  • The React landing page overrides any index.md file in this directory
  • Always test locally before committing changes
  • Consider the user journey from landing page → documentation → task completion