Understand docs-as-code
Promptless keeps your documentation current by proposing changes where your content lives. Most teams keep their docs in a Git repository as files a pull request can change, an approach called docs-as-code. If your hosted platform keeps content in its own database or WYSIWYG editor, moving to docs-as-code lets Promptless propose changes to it.
Use cases
Section titled “Use cases”Whether your docs need to move before you adopt Promptless depends on where the source lives today:
| Your situation | What to do |
|---|---|
| Your docs live in a hosted editor that keeps the content in its own database. | Move the content into a Git repository before a pilot. Start with Choose a platform. |
| Your team writes in DITA, reStructuredText, or another format that isn’t Markdown. | Keep the format. Promptless edits any text-based source format in Git. |
| You already publish from a Git-backed static site generator. | Skip the migration. Connect your repository, then set up your triggers. |
What docs-as-code means
Section titled “What docs-as-code means”Docs-as-code treats documentation the same way engineering teams treat source code:
- Content lives as source files in a Git repository. The files are often Markdown or MDX, but they can also be DITA, reStructuredText, a MadCap Flare project, or another authoring format.
- Changes go through pull requests, so every edit is reviewable, diffable, and revertable with the tools your engineers already use.
- A build tool, often a static site generator, publishes the site from those files. The repository is the source of truth, and the live site is a build artifact.
Because the content is versioned files, Promptless proposes an edit the same way a teammate does. It creates a branch, changes the files, and opens a PR that you review before it ships.
How Promptless works with docs-as-code
Section titled “How Promptless works with docs-as-code”Promptless works inside your existing review workflow. When a trigger activates, such as a merged code PR, a Slack thread, or a support ticket, Promptless drafts the documentation change. It commits the change to a branch in your docs repository and opens a pull request with citations to the sources that informed it. You review and merge that PR like any other.
Each part of that loop uses the docs as versioned files in a Git repository:
- Promptless reads the current content to learn your product, voice, and structure.
- Promptless writes its changes as a branch and a reviewable diff.
- Your platform rebuilds the published site from the merged files.
What “supported” looks like
Section titled “What “supported” looks like”Promptless publishes to any docs-as-code platform that builds from a GitHub or GitLab repository, whatever the tool or file format. Promptless works with Markdown and MDX, and also with DITA, reStructuredText, MadCap Flare, and FrameMaker (through a MIF intermediary).
Some platforms aren’t natively Git-based but sync or mirror their content to GitHub. Promptless supports those setups too, because it reaches the source through a repository it can branch from. See the supported platforms list for the tools teams most often run on Promptless.
Where to go next
Section titled “Where to go next”If your docs need to move, the rest of this section walks the migration end to end:
- Choose a platform, to pick a supported docs platform that fits your team
- Migrate to a new docs platform, to move your content off a hosted platform and into a Git repository
- Preserve URLs and redirects, to keep existing links working after the move
Open-source maintainers already on a Git-backed stack can start from the open-source quickstart, which covers the free program.