From 11b175efa0dd866122a262bcacdb2bcf60e8755e Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Tue, 12 May 2026 18:49:26 +0000 Subject: [PATCH] Add end-to-end tutorial for first PR-triggered docs update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduces a hands-on tutorial in the Getting Started section that walks users through the complete Promptless workflow: making a code change, opening a PR, reviewing the documentation suggestion, providing feedback, and publishing the update. Addresses the Diátaxis "Tutorials" quadrant gap identified in IA analysis. --- ...utorial-first-pr-triggered-docs-update.mdx | 220 ++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 src/content/docs/docs/getting-started/tutorial-first-pr-triggered-docs-update.mdx diff --git a/src/content/docs/docs/getting-started/tutorial-first-pr-triggered-docs-update.mdx b/src/content/docs/docs/getting-started/tutorial-first-pr-triggered-docs-update.mdx new file mode 100644 index 00000000..5327d531 --- /dev/null +++ b/src/content/docs/docs/getting-started/tutorial-first-pr-triggered-docs-update.mdx @@ -0,0 +1,220 @@ +--- +title: "Tutorial: Your First PR-Triggered Docs Update" +description: >- + Follow along as you make a code change, watch Promptless analyze it, and + review your first documentation suggestion +slug: docs/getting-started/tutorial-first-pr-triggered-docs-update +sidebar: + hidden: false + order: 3.5 +--- +import { Steps } from '@astrojs/starlight/components'; +import Info from '@components/fern/Info.astro'; +import Note from '@components/fern/Note.astro'; +import Success from '@components/fern/Success.astro'; +import Tip from '@components/fern/Tip.astro'; +import Warning from '@components/fern/Warning.astro'; + +This tutorial walks you through the complete Promptless workflow. You'll make a small code change, open a pull request, and watch Promptless analyze it and create a documentation suggestion—all in about 15 minutes. + +## What You'll Learn + +By the end of this tutorial, you'll know how to: + +- Trigger Promptless from a GitHub pull request +- Review a documentation suggestion in the Promptless dashboard +- Provide feedback and request edits +- Publish the final documentation update + +## Prerequisites + +Before starting, make sure you have: + +- A Promptless account ([sign up here](https://accounts.gopromptless.ai) if you haven't already) +- GitHub connected as a trigger source +- At least one documentation repository configured +- A code repository where you can open a test pull request + + +Haven't completed setup yet? Follow the [Setup & Quickstart](/docs/getting-started/setup-quickstart) guide first, then return to this tutorial. + + +## Step 1: Prepare Your Test Change + +For this tutorial, make a small code change with clear documentation implications. This helps Promptless recognize that docs need updating. + +Good examples of documentation-triggering changes: + +- Adding a new API endpoint or parameter +- Changing default configuration values +- Adding a new feature flag or environment variable +- Updating error messages users might encounter + + +If you don't want to modify production code, create a test branch with a README change that describes a fictional new feature. Promptless analyzes PR content, not just code syntax. + + +### Example: A Simple Feature Addition + +For this walkthrough, imagine you're adding a new `--verbose` flag to a CLI tool. Your change might look like: + +```diff + def run_command(args): ++ if args.verbose: ++ print("Starting operation with verbose logging enabled") + # existing logic +``` + +The key is making a change that a technical writer would want to document. + +## Step 2: Open a Pull Request + +Create a pull request with your change. Write a clear title and description—Promptless uses this context to understand what changed and why. + + +1. Push your branch to GitHub +2. Open a pull request against your main branch +3. Write a descriptive title (e.g., "Add --verbose flag for detailed output") +4. Include context in the description about what the change does and who it affects + + + +Promptless skips draft pull requests by default. Make sure your PR is marked as ready for review, or convert it from draft status. + + +**What to expect:** Within a few seconds of opening the PR, Promptless receives a webhook notification and begins analyzing your changes. + +## Step 3: Watch Promptless Analyze Your PR + +After you open the PR, Promptless: + +1. Reads the code diff, PR title, and description +2. Checks your existing documentation to understand current coverage +3. Determines whether the change requires documentation updates +4. If relevant, drafts a documentation suggestion + +**Where to see progress:** + +- **Slack notification** (if configured): Promptless sends a message when analysis starts and when the suggestion is ready +- **GitHub PR comment**: Promptless posts a comment on your PR linking to the documentation suggestion +- **Dashboard**: Visit [app.gopromptless.ai](https://app.gopromptless.ai) to see all suggestions + + +Analysis typically takes 1–3 minutes depending on the size of your change and how much context Promptless needs to gather. + + +### What If Promptless Doesn't Create a Suggestion? + +Not every code change needs documentation. Promptless might determine your change is: + +- Internal refactoring with no user-facing impact +- A bug fix that doesn't change documented behavior +- Test or CI configuration changes + +If you expected a suggestion but didn't get one, trigger Promptless manually by @mentioning it in a PR comment: + +``` +@promptless please document this change +``` + +## Step 4: Review the Documentation Suggestion + +When the suggestion is ready, click the link in your Slack notification or GitHub PR comment to open it in the Promptless dashboard. + +### Understanding the Suggestion View + +The dashboard shows you: + +- **Proposed changes**: The documentation updates Promptless drafted +- **Affected files**: Which documentation pages would be updated +- **Citations**: The sources Promptless used (your PR, related code, existing docs) +- **Reasoning**: Why Promptless made specific decisions + +### Checking the Diff + +Review the proposed documentation changes carefully. Ask yourself: + +- Is the information accurate? +- Does it match how the feature actually works? +- Is anything missing that users would need to know? +- Does the tone match your existing documentation? + + +Click on citations to see exactly what context Promptless used. This helps you understand why it made specific choices and catch any misinterpretations. + + +## Step 5: Provide Feedback and Request Edits + +Promptless suggestions are drafts, not final copy. Refine them through feedback. + +### Editing Through the Dashboard + +In the suggestion view, you can: + +- Edit the documentation directly in the web interface +- Request changes by leaving comments +- Ask Promptless to expand, clarify, or restructure sections + +### Editing Through Slack + +If you have Slack connected, reply in the Promptless thread with instructions: + +``` +Please add an example showing the verbose output format +``` + +``` +Move the configuration section before the usage section +``` + +### Editing Through GitHub + +Once Promptless opens a documentation PR, you can leave comments directly on the PR. Promptless monitors for feedback and can push additional commits in response. + + +Promptless remembers the conversation context, so you can give incremental feedback like "Also add..." or "Same thing for the other section." + + +## Step 6: Publish the Documentation Update + +When you're happy with the suggestion, you have two paths to publish: + +### If Auto-Publish Is Enabled + +Promptless automatically creates a PR in your documentation repository. You can: + +1. Review the PR like any other code change +2. Request additional edits through PR comments +3. Merge when ready + +### If Auto-Publish Is Disabled + +1. Click **Create PR** in the dashboard to generate the documentation PR +2. Review and merge the PR in your docs repository + + +Congratulations! You've completed your first PR-triggered documentation update with Promptless. + + +## What You Learned + +In this tutorial, you: + +- Made a code change and opened a pull request +- Watched Promptless automatically detect and analyze the change +- Reviewed a documentation suggestion in the dashboard +- Learned how to provide feedback through multiple channels +- Published the documentation update through your normal workflow + +## Next Steps + +Now that you've completed the basic workflow, explore these topics: + +- **[Working with Slack](/docs/how-to-use-promptless/working-with-slack)**: Trigger and manage suggestions directly from Slack +- **[Providing Feedback](/docs/how-to-use-promptless/providing-feedback)**: Learn more ways to refine Promptless suggestions +- **[GitHub PRs](/docs/configuring-promptless/triggers/git-hub-p-rs)**: Configure when and how PR triggers fire +- **[Core Concepts](/docs/getting-started/core-concepts)**: Understand triggers, context sources, and doc collections + + +Having trouble? Check [Getting Support](/docs/getting-started/getting-help) or contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). +