Documentation Platform

Designed and developed a comprehensive documentation platform for Shoreline.io that serves as the primary resource for users learning about Shoreline's incident management and automation capabilities. The platform features world-class UI/UX practices, dynamic content delivery, user-specific documentation, content versioning, cloud provider integration, state-of-the-art authoring tools, policy-based auth, and API-ready product integration.

The platform supports multiple content types, including tutorials, API documentation, video guides, custom workshops, dynamic configuration generators, and interactive guides. Built with performance and user experience as top priorities, the site implements modern development strategies including static generation, optimized media, automatic CDN propagation, and progressive loading.

Key Features

• Dynamic content includes and terminology management for consistent cross-references
• Versioned content system with environment-specific release management (dev/staging/production)
• Interactive code examples with provider-aware configuration generators
• Policy-based access control for private content delivery to specific customer segments
• Custom DSL syntax highlighting with Monaco editor integration for Shoreline's Op language
• Dynamic provider configuration with real-time content updates based on the user's cloud environment
• Advanced search functionality with Algolia integration across all content
• Multi-modal documentation supporting CLI, UI, Notebook, and Terraform workflows

Technical Architecture

Built with a modern, scalable tech stack optimized for performance and developer experience:

• Next.js, React, TypeScript, and Tailwind CSS for a modern front-end codebase
• Node.js for serverless functions, tests, and CI/CD scripts
• Markdown and MDX for content authoring
• MongoDB for user data
• Redux for complex state management, Zustand for simpler state management
• Algolia for search functionality
• Posthog for analytics and user behavior tracking
• Amazon S3 & CloudFront for media asset CDN
• Vercel for global content delivery, edge caching, and serverless functions
• Prettier, ESLint, and Vale for code formatting and linting
• GitHub Actions for some CI/CD tasks

UI and UX Design

For ease of authorship and maintenance, I wrote all the content on the Shoreline.io documentation platform using a custom version of Markdown. To provide a consistent user experience and visual appearance, I developed a set of reusable, documentation-oriented UI/UX components and features implemented throughout the site.

• Custom CLI command syntax highlighting for code examples. Shoreline's Op language is a custom DSL that allows users to interact with the Shoreline platform through a command-line interface. The documentation platform includes custom syntax highlighting for Op commands, making it easy for users to read and understand command examples. The pseudo-terminal leverages the Monaco editor and a custom language definition schema.
• Dynamic provider configuration with real-time updates for user-specific documentation paths. The system enables authors to define provider-specific content and delivers documentation tailored to each user's cloud provider and configuration, improving relevance and usability. Example
• Interactive code examples with syntax highlighting. This feature allows users to see code snippets in context, with content tailored to their specific use cases. For example, the Kubernetes Helm installation guide features an API-style property list linked to other related, interactive sections of the documentation. Therefore, if a user changes the active version in the dropdown or navigates from their private Shoreline installation, the documentation updates in real-time to reflect the correct properties and generates an aggregate configuration file that can be copied and pasted into their Helm chart.
• Terminology component to simplify cross references and definitions of key terms across the documentation. The terminology component simplifies cross‑references and definitions, enabling standardized references to complex topics and ensuring links always resolve to the latest article, even after renames or relocations.
• Dynamic content allows authors to reuse and update shared content and files across multiple articles, ensuring consistent updates and reducing manual edits.
• CLI output with dynamic content. For example, the CLI reports host, region, and AZ information based on the user's specified cloud provider.
• A dynamic table of contents updates based on visible page content, letting authors work freely with dynamic content while always reflecting the page's current state. Example (try changing the provider and/or the active tabs within provider-specific content)
• Collapsible sections for progressive disclosure of complex topics.
• Getting started cards guide users through the initial setup and configuration.
• Inline code blocks for code snippets that users can copy and paste directly into their terminal or code editor. Example
• Shoreline UI components for consistent styling and behavior between the documentation platform and the Shoreline product.
• Mode selection for users to select between different modes of operation, including "CLI", "UI", "Notebook", and "Terraform". Modes allow users to see documentation tailored to their specific use case and preferred method of interaction with the Shoreline platform. Example
• Tabs, tags, badges, and many other visual UI components that enhance UX and make it easy to navigate complex topics. Example
• Code-based diagrams powered by Mermaid.js.

Private Content & Authorization

The documentation platform also features a custom policy-based access control system, enabling the display of private content based on user roles and permissions. The system allows authors to easily create private content based on one or more of the following criteria:

• The article's path (e.g., /installation/kubernetes/private)
• The published environment (e.g., production, staging, development)
• The user's identity (e.g., admin, user, viewer)

For example, adding the following to the frontmatter of an article makes it accessible to users with the developer role:

auth:
  tag: role
tags:
  role: developer

This configuration requires that the user has access to the relative path of the published article.

auth:
  path: true

A policy statement might have the following definition, giving the user access to the /workshops/acme path (and all child paths), along with access to role:developer tagged content:

"policy": {
  "statement": [
    {
      "path": "/workshops/acme"
    },
    {
      "allow": true,
      "tag": {
        "name": "role",
        "value": "developer"
      }
    }
  ]
}

This system provides specific customers with access to private documentation content, while also allowing authors to create sections for internal Shoreline employees, including many guides on using the documentation platform itself.

Versioned Content

The documentation platform supports dynamic versioned content, allowing users to view documentation for specific versions of the Shoreline platform. This version-aware system helps users who need to reference older releases or plan an upgrade.

The optional environment array of a release defines which deployment environment(s) that release is available for. By default, a release is available in all deployment environments. However, specifying one or more environments restricts that release.

This is most useful when working on upcoming release-specific content or articles that should be sharable with others but aren't yet publicly available.

For example, consider the following release collection:

[
  {
    "environment": ["development"],
    "tag": "release-14.0.0",
    "version": "14.0.0"
  },
  {
    "tag": "release-12.1.2",
    "version": "12.1.2"
  },
  {
    "environment": ["development", "staging"],
    "tag": "release-13.3.2",
    "version": "13.3.2"
  }
]

This results in the following release availability:

Only those releases available to the deployed environment are visible and selectable by the user.

Similarly, content can be versioned using the <Release> inline component or by using the version frontmatter property to restrict an entire article to a specific version.

The feature flag system enables authors to associate content with a specific version, product feature, or both. The platform automatically publishes and displays the content only after meeting all required criteria.

Impact & Results

The documentation platform has become a cornerstone of Shoreline's user experience:

• 65% improvement in user onboarding success rates 2
• Significant reduction in support tickets through comprehensive self-service content
• 185,000+ words of technical content authored across 100+ articles
• High user engagement with interactive tutorials and video content

The platform continues to serve hundreds of users daily and has become a key differentiator for Shoreline's customer base.