Workflow READMEs

# Overview

As workflows grow in complexity, understanding them becomes just as important as executing them. Before Workflow READMEs, context lived in people’s heads, Slack threads, or external docs that quickly drifted out of sync.

This feature focused on bringing documentation directly into the workflow itself.

Workflow READMEs in BuildShip are implemented as first-class pages that live alongside workflows, not as an afterthought or static text field.

# Why READMEs Needed to Live Inside the Product

Workflows are often shared, cloned, or revisited weeks later. Without context, it is hard to answer basic questions:

• Why does this workflow exist?
• What inputs does it expect?
• What assumptions does it make?
• How should it be customized?

External documentation breaks easily, and inline comments are rarely sufficient. READMEs needed to be tightly coupled to the workflow while remaining flexible and expressive.

# Creating a README

READMEs are created directly from the workflow top bar.

When a user selects Create Read Me, the feature uses a dedicated hook to trigger page creation. Under the hood, this calls a shared atom responsible for creating new pages in Firestore under the project’s pages collection.

Each README starts from a predefined Markdown template. This gives users a structured starting point instead of a blank editor, encouraging better documentation by default.

To keep projects organized, the system ensures that READMEs and workflows live together. If a workflow is not already in a folder, a new folder is created automatically and both the workflow and its README are moved into it.

This small detail prevented a lot of long-term clutter.

# Editing Experience

The README editor is built using a rich WYSIWYG Markdown editor (pronounced "wiz-ee-wig", standing for "What You See Is What You Get"), rather than a raw text area.

Users can write standard Markdown while also having access to richer features such as tables, images, and code blocks. Image uploads are handled through the BuildShip API, so assets remain accessible and stable.

For more advanced use cases, the editor supports Sandpack, allowing interactive code snippets to live directly inside the README. This made READMEs useful not just for description, but for interactive teaching and onboarding.

All editing logic is centralized in a dedicated PageEditor component, keeping the feature modular and extensible.

# Real-Time Collaboration and Persistence

READMEs are backed by Firestore and use real-time synchronization.

The usePage hook handles two-way data flow:

• It listens for updates from Firestore so multiple users can see changes live.
• It persists local edits back to the database with debounced persistence to avoid excessive writes.

This allowed READMEs to behave more like collaborative documents than static files, without exposing that complexity to users.

# Routing and Navigation

Each README is accessed through a dedicated page route in the v2 routing system.

This keeps documentation navigable, linkable, and shareable, while still being clearly associated with a specific workflow. READMEs are not hidden modals or side panels—they are full pages that can grow as workflows grow.

Workflow READMEs unlocked several practical benefits:

• Clarity & Reuse: Shared workflows became easier to understand and reuse across teams.
• Comprehensive Guidance: Templates could explain setup and customization clearly with interactive snippets.
• Contextual Decisions: Teams could document decisions close to execution logic.
• Frictionless Onboarding: Onboarding new users and teammates became significantly easier.

Most importantly, documentation stopped being optional. By making it easy and integrated, it became an organic part of the workflow authoring process.