From 0e0fe4c55c118be98ef5c8a1d68a962653e69e70 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 20:49:49 +0000 Subject: [PATCH 1/3] Update guides/feature-releases.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Mintlify-Source: dashboard-editor --- guides/feature-releases.mdx | 213 ++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 guides/feature-releases.mdx diff --git a/guides/feature-releases.mdx b/guides/feature-releases.mdx new file mode 100644 index 000000000..8549d3228 --- /dev/null +++ b/guides/feature-releases.mdx @@ -0,0 +1,213 @@ +--- +title: Feature release process +description: How Mintlify releases and documents new features +--- + +This guide explains how Mintlify releases features and updates documentation based on our established workflow patterns. + +## Release workflow + +Mintlify follows a structured process for releasing features that ensures documentation stays synchronized with product changes. + +### 1. Feature development + +Features are developed in the product repository and merged to the main branch. Each feature includes: + +- Implementation code +- Tests +- Internal documentation + +### 2. Documentation drafting + +When a feature is ready for release, documentation is created or updated through one of these methods: + +**Agent-generated documentation**: The Mintlify agent automatically detects new features from commits and pull requests, then drafts documentation that explains: +- What the feature does +- When to use it +- How to configure it +- Code examples where relevant + +**Manual documentation**: For complex features or those requiring detailed explanation, documentation is written manually following the same structure. + +### 3. Review and refinement + +Documentation goes through a review process: + +1. **Initial draft**: Agent or human creates the first version +2. **Technical review**: Verify accuracy and completeness +3. **Editorial review**: Ensure clarity, consistency, and adherence to style guidelines +4. **Approval**: Final sign-off before merge + +### 4. Translation + +After the English documentation is approved, translations are generated for supported languages (Spanish, French, Chinese). Translation pull requests: + +- Are created automatically by the agent +- Reference the original English PR +- Maintain consistent structure across languages +- Are reviewed for accuracy + +### 5. Publication + +Once approved, documentation is merged and automatically deployed. The process includes: + +- Merging the documentation PR +- Automatic deployment to production +- Navigation updates if new pages were added +- Changelog entries for significant features + +## Documentation patterns + +### Feature documentation structure + +New feature documentation follows this pattern: + +```markdown +--- +title: Feature name +description: Brief summary of what the feature does +--- + +Brief introduction explaining the feature's purpose. + +## When to use this + +Explain use cases and scenarios where this feature applies. + +## How it works + +Describe the feature's behavior and any important concepts. + +## Configuration + +Show how to set up and configure the feature. + +\`\`\`json +{ + "example": "configuration" +} +\`\`\` + +## Examples + +Provide practical examples showing the feature in action. + +## Related + +Link to related documentation. +``` + +### Commit message conventions + +Documentation commits follow these patterns: + +- **New features**: `Add [feature name] documentation` +- **Updates**: `Update [page name] to [describe change]` +- **Translations**: `Translate [feature name] to es, fr, zh` +- **Fixes**: `Fix [issue] in [page name]` +- **Agent-generated**: Include `Generated-By: mintlify-agent` in commit body + +### Pull request workflow + +Documentation PRs include: + +1. **Descriptive title**: Clear summary of changes +2. **Agent attribution**: `Generated-By: mintlify-agent` for automated PRs +3. **Co-authors**: Credit both the agent and human reviewers +4. **Review process**: At least one approval before merge +5. **Linked issues**: Reference related product PRs or issues + +## Release timing + +### Immediate documentation + +These changes are documented immediately upon release: + +- New configuration options +- API endpoint changes +- Breaking changes +- Security updates + +### Batched documentation + +These updates may be batched: + +- Minor UI improvements +- Bug fixes that don't affect usage +- Internal refactors +- Performance improvements + +### Changelog entries + +Significant features receive changelog entries that: + +- Announce the feature +- Link to detailed documentation +- Explain the benefit to users +- Include release date + +## Best practices + +### For new features + +1. **Document before release**: Ensure documentation is ready when the feature ships +2. **Include examples**: Show real-world usage, not just configuration +3. **Update navigation**: Add new pages to appropriate sections +4. **Cross-reference**: Link from related pages to the new feature +5. **Test examples**: Verify all code examples work as documented + +### For updates + +1. **Update existing pages**: Prefer updating over creating new pages +2. **Maintain accuracy**: Remove outdated information +3. **Version appropriately**: Note when features were added or changed +4. **Update screenshots**: Keep visual examples current + +### For deprecations + +1. **Announce early**: Give users time to migrate +2. **Provide alternatives**: Show what to use instead +3. **Document migration**: Create step-by-step migration guides +4. **Update examples**: Replace deprecated patterns in all docs + +## Automation + +Mintlify uses automation to maintain documentation quality: + +### Workflows + +Automated workflows handle: + +- **Draft documentation for new features**: Monitors product repository for changes +- **Translation updates**: Keeps all languages synchronized +- **Changelog generation**: Creates release notes from PRs +- **Link checking**: Validates internal and external links +- **Style enforcement**: Runs Vale to check writing quality + +### Agent integration + +The Mintlify agent assists with: + +- Detecting documentation needs from code changes +- Drafting initial documentation +- Suggesting improvements to existing pages +- Maintaining consistency across pages +- Translating content to supported languages + +## Quality standards + +All feature documentation must meet these criteria: + +- **Accurate**: Reflects actual product behavior +- **Complete**: Covers all configuration options and use cases +- **Clear**: Written for the target audience +- **Tested**: All examples verified to work +- **Accessible**: Follows accessibility guidelines +- **Searchable**: Optimized for search and discovery + +## Related + +- [Automate documentation updates](/guides/automate-agent) +- [Maintenance](/guides/maintenance) +- [Content types](/guides/content-types) +- [Style and tone](/guides/style-and-tone) From 4475c3c293c7b4b693cf2f5a4ebd2ccd13a42733 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 20:50:01 +0000 Subject: [PATCH 2/3] Update docs.json Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Mintlify-Source: dashboard-editor --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 436b3e0fb..ce4964e12 100644 --- a/docs.json +++ b/docs.json @@ -300,6 +300,7 @@ "guides/content-types", "guides/content-templates", "guides/custom-layouts", + "guides/feature-releases", "guides/improving-docs", "guides/internationalization", "guides/linking", From e5f61f4f50a79cc4e511cbefd935e65e4311593c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 20:50:15 +0000 Subject: [PATCH 3/3] Update guides/index.mdx Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Mintlify-Source: dashboard-editor --- guides/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/guides/index.mdx b/guides/index.mdx index f214f3ed4..dd16b4049 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -33,6 +33,7 @@ Make your documentation best in class. - [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations. - [Content templates](/guides/content-templates): Copy and modify templates for each content type. - [Custom page layouts](/guides/custom-layouts): Use page modes and components to build landing pages and other custom layouts. +- [Feature release process](/guides/feature-releases): Understand how Mintlify releases and documents new features. - [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation. - [Internationalization](/guides/internationalization): Set up multi-language documentation to reach global audiences. - [Linking](/guides/linking): Create internal links, reference API endpoints, and maintain link integrity across your documentation.