Update AI assistant documentation for wiki management
This commit is contained in:
127
.ai-workflows/wiki-documentation.md
Normal file
127
.ai-workflows/wiki-documentation.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Wiki Documentation Management
|
||||
|
||||
This document outlines the process for maintaining and updating the wiki documentation for the "Fix 'Plugin file does not exist' Notices" plugin.
|
||||
|
||||
## Wiki Structure
|
||||
|
||||
The wiki documentation is stored in the `.wiki` directory in the repository. This directory contains Markdown files that are automatically synced to the GitHub wiki when changes are pushed to the main branch.
|
||||
|
||||
### Key Files
|
||||
|
||||
- **Home.md**: The landing page of the wiki
|
||||
- **_Sidebar.md**: The sidebar navigation for the wiki
|
||||
- **README.md**: Instructions for contributing to the wiki
|
||||
- **Other .md files**: Individual documentation pages
|
||||
- **assets/**: Directory for images and other assets used in the documentation
|
||||
|
||||
## Documentation Synchronization
|
||||
|
||||
To ensure consistency across all documentation sources, follow these guidelines:
|
||||
|
||||
### When Updating README.md or readme.txt
|
||||
|
||||
1. Identify the sections that need to be reflected in the wiki documentation
|
||||
2. Update the corresponding wiki pages in the `.wiki` directory
|
||||
3. Ensure that feature descriptions, usage instructions, and other relevant information are consistent across all documentation sources
|
||||
4. Update the changelog in all locations:
|
||||
- README.md
|
||||
- readme.txt
|
||||
- CHANGELOG.md
|
||||
- .wiki/Changelog.md
|
||||
|
||||
### When Adding New Features or Functions
|
||||
|
||||
1. Document the feature in the appropriate README.md and readme.txt sections
|
||||
2. Create or update the corresponding wiki page in the `.wiki` directory
|
||||
3. Include:
|
||||
- Feature description
|
||||
- Usage instructions
|
||||
- Examples
|
||||
- Screenshots (if applicable)
|
||||
- Any relevant configuration options
|
||||
|
||||
### When Adding Hooks or Filters
|
||||
|
||||
1. Document the hook or filter in the README.md file
|
||||
2. Update or create the `.wiki/Hooks-and-Filters.md` page with:
|
||||
- Hook/filter name
|
||||
- Description
|
||||
- Parameters
|
||||
- Return value
|
||||
- Example usage
|
||||
- Default behavior
|
||||
|
||||
### When Updating Code Structure
|
||||
|
||||
1. Update the `.wiki/How-It-Works.md` page to reflect the new code structure
|
||||
2. If the changes affect the plugin's architecture, update any relevant diagrams or explanations
|
||||
3. Ensure that the documentation accurately reflects the current state of the codebase
|
||||
|
||||
## Wiki Maintenance Workflow
|
||||
|
||||
### Regular Maintenance
|
||||
|
||||
1. Review the wiki documentation monthly to ensure it's up-to-date
|
||||
2. Check for broken links, outdated information, or missing content
|
||||
3. Update screenshots and examples to reflect the latest version of the plugin
|
||||
|
||||
### Release-Driven Updates
|
||||
|
||||
1. Before each release, review and update all wiki documentation
|
||||
2. After the release, update the `.wiki/Changelog.md` file with the latest changes
|
||||
3. Ensure that new features or changes are properly documented in the wiki
|
||||
|
||||
### User-Driven Updates
|
||||
|
||||
1. Monitor GitHub issues and WordPress.org support forums for common questions
|
||||
2. Update the FAQ and troubleshooting sections based on user feedback
|
||||
3. Add new examples or clarifications based on user questions
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Content Guidelines
|
||||
|
||||
- Use clear, concise language
|
||||
- Include step-by-step instructions for complex tasks
|
||||
- Use screenshots or diagrams to illustrate concepts
|
||||
- Provide code examples for developers
|
||||
- Keep the documentation organized and easy to navigate
|
||||
|
||||
### Formatting Guidelines
|
||||
|
||||
- Use consistent Markdown formatting
|
||||
- Use descriptive file names with hyphens instead of spaces
|
||||
- Include a title at the top of each page using a level 1 heading (`# Title`)
|
||||
- Use appropriate heading levels (H2, H3, etc.) for section organization
|
||||
- Include links to related pages where appropriate
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
- When working on code changes, consider documentation updates as part of the same task
|
||||
- Create or update wiki documentation in the same branch as code changes
|
||||
- Include documentation updates in pull request descriptions
|
||||
- Request documentation review as part of the code review process
|
||||
|
||||
## Automatic Syncing
|
||||
|
||||
When changes are pushed to the main branch and include modifications to files in the `.wiki` directory, a GitHub Action will automatically sync these changes to the GitHub wiki. This ensures that the documentation is always up-to-date with the latest changes.
|
||||
|
||||
The sync workflow is defined in `.github/workflows/sync-wiki.yml` and runs whenever changes to the `.wiki` directory are pushed to the main branch.
|
||||
|
||||
## Documentation Testing
|
||||
|
||||
Before pushing documentation changes:
|
||||
|
||||
1. Preview the Markdown files locally to ensure proper formatting
|
||||
2. Check all links to ensure they work correctly
|
||||
3. Verify that code examples are correct and up-to-date
|
||||
4. Ensure that screenshots accurately reflect the current UI
|
||||
|
||||
## Troubleshooting Wiki Sync Issues
|
||||
|
||||
If the wiki sync fails:
|
||||
|
||||
1. Check the GitHub Actions logs for error messages
|
||||
2. Verify that the wiki repository exists and is accessible
|
||||
3. Ensure that the GitHub token has the necessary permissions
|
||||
4. Try manually syncing the wiki by following the steps in the workflow file
|
||||
Reference in New Issue
Block a user