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 seamless integration with the main product.

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 user's cloud environment
• Advanced search functionality with Algolia integration across 185,000+ words of 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 and ESLint for code formatting and linting
• GitHub Actions for some CI/CD tasks

UI and UX Design

For ease of authorship and maintenance, all the content on the Shoreline documentation platform was written in Markdown. In order to provide the best user experience and provide a consistent look and feel, I developed a set of reusable documentation-oriented UI/UX components and features that can be easily implemented anywhere in 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. This was implemented using the Monaco editor and a custom language definition schema.
• Interactive CLI terminal that allows users to run certain commands from the docs and see the output in real-time. Since every Op DSL command throughout the documentation is powered by the Monaco editor, authenticated users can interact with some terminal commands directly within the documentation.
• Dynamic provider configuration with real-time updates for user-specific documentation paths. This allows the author to define provider-specific content and also allows users to see documentation tailored to their specific cloud provider and configuration, enhancing the relevance and usability of the content. 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 has an API-style property list that is tied to other related, interactive parts of the documentation. So, 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 will even output an aggregate configuration file that can be copied and pasted into their own Helm chart.
• CLI output with dynamic content. For example, the CLI reports host, region, and AZ information based on the user's specified cloud provider.
• Code-powered diagrams powered by Mermaid.js.
• Dynamic table of contents that updates based on the visible content of the page. This ensures that the author can freely work with dynamic content and the table of contents will always reflect the current state of the page. 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 that guide users through initial setup and configuration.
• Inline code blocks for code snippets 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.
• Terminology component to simplify cross references and definitions of key terms across the documentation. This makes it easy to reference a complex topic or article by a standardized term, and ensures the platform will always link to the most up-to-date version of the article, even if it is renamed or moved in the future.
• Dynamic content includes for reusable content and files that can be easily updated across multiple articles. This allows for consistent content updates and reduces the need for manual changes across the documentation.
• Mode selection for users to select between different modes of operation, including "CLI", "UI", "Notebook", and "Terraform". This allows 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

Private Content & Authorization

The documentation platform also includes a custom policy-based access control system that allows for private content to be displayed based on user roles and permissions. The system was designed to allow 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 was used to give specific customers access to private documentation content, create sections for internal Shoreline employees, and even write many of the 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 is particularly useful for users who need to reference older versions of the product or who are in the process of upgrading.

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 version restrict an entire article.

A feature flag system was also implemented to allow content to be tied to a version, a product feature, or both. Only when all necessary criteria were met would the content be automatically published and visible to users.

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 experience.