QMIMS CLI Tool

Best Practices

Tips and recommendations for using qmims effectively

This section provides best practices and recommendations for using qmims effectively. Following these guidelines will help you create high-quality documentation for your projects.

README Structure

A good README typically includes:

Essential Information
Core project details
  • Project title and description
  • Badges (build status, version, license)
  • Key features
Usage Information
How to use the project
  • Installation instructions
  • Usage examples with code
  • API documentation (if applicable)
Additional Information
Supporting details
  • Contributing guidelines
  • License information
  • Acknowledgements

Using qmims Effectively

Start with Auto Mode

For new projects, start with auto mode to generate a comprehensive README. This will analyze your project and create a well-structured document.

qmims generate --mode auto

Refine with Templates

Use templates for more structured documentation. Choose a template that matches your project type for consistent formatting.

qmims generate --mode template:detailed

Fine-tune with Embedded Instructions

Add specific instructions for precise control over content generation. This is especially useful for updating specific sections of your README.

qmims edit

Set Default Configuration

Configure qmims to match your preferences for a more streamlined workflow.

qmims config setup

Create Custom Templates

For projects with specific documentation needs, create custom templates that match your requirements.

qmims templates add my-template path/to/template.md

Use Dry Run

Preview changes before applying them to ensure they meet your expectations.

qmims generate --dry-run

Combine with Git Workflow

Integrate README generation into your development workflow for consistent documentation.

qmims generate && git add README.md && git commit -m "docs: update README"

Writing Effective Instructions

When writing embedded instructions for qmims, follow these guidelines:

GuidelineExample
Be specific about what you want<!-- qmims: Generate a step-by-step installation guide for this Node.js library, including all dependencies -->
Provide context about the project<!-- qmims: Describe this REST API framework, highlighting its performance benefits and scalability features -->
Specify the desired format<!-- qmims: List the API endpoints as a table with columns for Method, Endpoint, Description, and Required Parameters -->
Indicate the level of detail<!-- qmims: Provide a concise overview (2-3 sentences) of the project's purpose and main features -->

Documentation Maintenance

Keeping your documentation up-to-date is essential. Here are some best practices for maintaining your README:

  • Regular Updates: Update your README whenever you make significant changes to your project
  • Version Alignment: Ensure your documentation version matches your code version
  • Automated Updates: Use CI/CD pipelines to automatically update documentation
  • Targeted Edits: Use qmims edit with embedded instructions to update specific sections
  • Review Generated Content: Always review AI-generated content for accuracy

Example Workflow

Here's an example workflow for creating and maintaining documentation with qmims:

  1. Initial Setup:
    # Configure qmims
qmims config setup

# Set default template
qmims config set defaults.templateName detailed
  2. Generate Initial README:
    # Generate README in auto mode
qmims generate --dry-run

# Review and apply changes
qmims generate
  3. Regular Updates:
    # Add embedded instructions to README.md for sections that need updates
# Edit README with embedded instructions
qmims edit --dry-run

# Review and apply changes
qmims edit
  4. Version Updates:
    # Update version-specific information
qmims edit

# Commit changes
git add README.md
git commit -m "docs: update README for version X.Y.Z"
git push