Style Guides

Style Guides

Purpose

The purpose of style guides are to specify a style guide URL or content that the AI should follow when generating documentation.

Using Style Guides

  • A global style guide can be set during onboarding or later at https://app.doc.holiday/settings/config
    • The global style guide is optional and is applied in addition to any publication-specific style guides
  • A style guide can also be specified for each publication
  • Style guides can be referenced in an issue, pull request, merge request, or release with syntax ...Style Guide: <link>

When multiple style guides are used, they are applied in the above order. Doc Holiday combines all referenced style guides into a single set of guidance. Duplicate style guide content, or links, are ignored.

Style Guide Support

Doc Holiday supports style guides written in raw text, HTML, and markdown.

Supported URL Types

  • Google Docs URLs (e.g., https://docs.google.com/document/d/...)
    • Prerequisite: Either make the document publicly accessible, or connect a Google Drive account that has access to the document and share it with the service account used for Doc Holiday
  • Notion page URLs (e.g., https://www.notion.so/...)
  • Confluence page URLs (e.g., https://yourcompany.atlassian.net/wiki/pages/viewpage.action?pageId=123456)
  • Public URLs (e.g., https://github.com/Sandgarden-Demo/styleguide-examples/blob/main/documentation_dspy.md)
    • Any unauthenticated, public HTML, Text, or Markdown URL is supported

Simple Style Guide Example 

# Documentation Style Guide
 
## Writing Guidelines
- Use clear, concise language
- Include code examples where appropriate
- Use consistent formatting for headers and lists
- Always include a brief description for new features
 
## Code Examples
- Use syntax highlighting
- Include comments for complex logic
- Show both input and expected output
 
## Structure
- Start with an overview
- Include step-by-step instructions
- End with troubleshooting tips

For more expansive style guide examples, check out the Sandgarden sample repository: https://github.com/Sandgarden-Demo/styleguide-examples

Supporting Time-Windowed Documentation Requests

Doc Holiday can generate documentation and release notes for commits within a specific time window (such as “the last 3 days”). To ensure your style guide is optimized with these workflows, consider adding clear expectations for time-windowed documentation and release note updates. For example:

## Release Note Updates
- Doc Holiday may be asked to generate updates based on a specific date or time range.
- When processing requests such as "generate release notes for the last 3 days", collect all commits and notable changes during that period, grouped by feature or area.
- Format release notes and documentation diffs as additive since the last time point.
- Example section header: "Changes from August 23–August 26, 2025"

Style Guide Best Practices

  • Describe the directory structure of the code and documentation repositories:
    • Which parts of the application live in which files and folders?
    • Which parts of the application are most likely to have customer-facing changes when code commits are made?
    • Where should the documentation and release notes go? Which files and directories cover which topics and sets of functionality?
  • For example, here is a snippet describing part of Sandgarden’s code base:
**Project Structure**

This project is a mono repo containing several sub-projects. Each project has its own directory. There are multiple applications that share a common API layer. Front-end applications are written in Typescript and use Next.js. The back-end API is written in Go.
 
- sfs/ - The Go back-end for the common API.
  - js - the root directory for JavaScript code. Sandgarden has a number of NextJS web applications. Each app is structured as pnpm workspace that descends from the root workspace defined in this directory js.apps
  - js/apps/sfs - The front-end web application for an AI assisted customer support SaaS
  - js/apps/doc.holiday - The front-end web application for doc.holiday an AI documentation writer
  - js/packages/* - shared code used by all front-end applications
  • Similarly, here’s a snippet describing the Sandgarden for Support documentation repository:
Sandgarden for Support is built around distinct AI automations that automated particular workflows for support teams. The documentation is organized in the same way:
- Each automation has its own documentation page
- Each automation page states the requirements for running the automation and then gives an explanation of how it works
- These should be in distinct sections titled "Requirements" and "How it works". The Requirements section should always come first.
  • Doc Holiday supports using multiple style guides, for different types of generated content. Creating a different publication for each type of content, each with their own style guide, will align content with your workflows and brand voice.
    • For example, having separate publications and style guides for bulleted changelogs covering every code change, product marketing release announcements for customers, and updating all existing public documentation.
  • Provide as many illustrative examples as possible. Here is an example from a style guide showing Doc Holiday how to create and amend a running release notes document:
---
title: Release Notes
description: Brief description of the thing
type: docs
weight: 7
---

## 2025-08-08
### New Features
- **Published Date Display**: Show publication date on docs pages with customizable format and locale (commit 9ce0ddc)
- **Gemini LM Integration**: Added documentation for authenticating and instantiating Gemini as a language model provider (commit 540772d)
- **PEP 604 Union Types**: Support `int | None`-style annotations in inline signatures (commit 95c0e4f)
- **Real-World Tutorials**:
  - Module development tutorial (commit 7d675c9)
  - `llms.txt` documentation generator tutorial (commit 94299c7)
  - Email extraction system tutorial (commit dc64c67)
  - Financial analysis agent tutorial using ReAct + Yahoo Finance (commit 4206d49)

### Enhancements
- **Async & Thread-Safe Settings**: Refactored context management for reliable async/threaded behavior (commit dd8cf1c)
- **Reusable Stream Listener**: `allow_reuse` flag to reuse listeners across concurrent streams (commit 64881c7)

### Bug Fixes
- **Pydantic v2 Compatibility**: Updated `json_adapter` to use `__config__` with `ConfigDict`, fixed related tests (commit 63020fd)
- **Custom Type Extraction**: `BaseType` now handles nested annotations and Python 3.10 compatibility (commit 4f154a7)
- **OpenTelemetry Logging**: Prevent handler conflicts by refining setup/removal logic (commit 3e1185f)
- **Inspect History Audio**: Restore display of `input_audio` objects to show format and length (commit a6bca71)
- **Completed-Marker in Conversations**: Add `[[ ## completed ## ]]` marker in ChatAdapter/JSONAdapter histories (commit dd971a7)
- **Stream Listener Spacing**: Fix missing spaces to detect start identifiers correctly (commit b5390e9)
- **Invalid LM Error Messages**: Clearer errors when LM is not loaded, incorrect type, or invalid instance (commit 0a6b50e)
- **`forward` Usage Warning**: Warn users against calling `.forward()` directly, prefer instance call (commit 56efe71)

## 2025-08-01
### New Features
- **XMLAdapter**: Handle XML-formatted input/output with comprehensive unit tests (commit 716e82c)
- **Databricks LM Update**: Default model switched to `llama-4`; added API key and base-URL configuration (commit 7a00238)
- **Real-World Tutorials**:
  - Memory-enabled conversational agent tutorial (commit 8b3f23a)
  - AI adventure game tutorial with modular game framework (commit 7483cf5)
  - Documentation automation tutorial (commit 547aa3e7)

### Enhancements
- **Global `max_errors` Setting**: Configure maximum error thresholds across components (commit 19d846a)
- **MLflow Tracing Tutorial**: Guide on using MLflow for DSPy model prediction tracing (commit 47f3b49)

### Bug Fixes
- **Cache Key Optimization**: Compute cache key once per request and deep-copy to prevent side effects (commit 07158ce)
- **Optional Core Dependencies**: Move `pandas`, `datasets`, and `optuna` to extras to slim core install (commit 440101d)
- **Non-Blocking Streaming**: Ensure status message streaming is asynchronous and non-blocking (commit a97437b)
- **Async Chat/JSONAdapter**: Support async calls and JSON fallback when structured formatting fails (commit 1df6768)
- **PEP 604 in ChainOfThought**: Fix Union-type handling for class signatures to avoid type-check errors (commit dc9da7a)
- **JSONAdapter Errors**: Let errors propagate instead of wrapping as `RuntimeError` for transparency (commit 734eff2)
Activity LogConfiguration