Skip to main content

Content Quality Badges

This guide explains how to add and interpret content quality badges for the RallyPoynt OS documentation.

Available Badges

The RallyPoynt OS repository includes several badges that indicate the status and quality of the documentation:

  1. Documentation Validation: Shows whether the documentation passes basic validation checks

    ![Documentation Validation](https://github.com/your-organization/rallypoynt-os/actions/workflows/docs-workflow.yml/badge.svg)

  2. Content Quality Score: Indicates the overall quality score of documentation

    ![Content Quality Score](https://img.shields.io/badge/Content%20Quality-7.5%2F10-brightgreen)

    Color codes for quality scores:

    • Red: 1-4 (Needs significant improvement)
    • Yellow: 5-6 (Acceptable)
    • Green: 7-10 (Good to excellent)

Adding Badges to README

To add these badges to your README.md file, insert the markdown code at the top of the file under the title:

# Project Title

![Documentation Validation](https://github.com/your-organization/rallypoynt-os/actions/workflows/docs-workflow.yml/badge.svg)
![Content Quality Score](https://img.shields.io/badge/Content%20Quality-7.5%2F10-brightgreen)

Automated Badge Updates

The Content Quality Score badge is automatically updated through GitHub Actions:

  1. The docs-workflow.yml GitHub Action runs the content quality assessment
  2. It calculates the average score across all documentation files
  3. A script updates the badge in the README.md file with the current score
  4. The changes are committed back to the repository

This ensures the badge always reflects the current state of the documentation quality.

Manual Badge Updates

To manually update the badge:

  1. Run the content quality assessment locally:

    node scripts/js/content-quality-cli.js --file=docs/**/*.md > quality-report.txt

  2. Calculate the average score from the report

  3. Update the badge URL in the README.md with the new score

    ![Content Quality Score](https://img.shields.io/badge/Content%20Quality-YOUR_SCORE%2F10-COLOR)

    Replace YOUR_SCORE with the calculated score and COLOR with:

    • red for scores 1-4
    • yellow for scores 5-6
    • brightgreen for scores 7-10

Interpreting Quality Scores

The content quality score is calculated based on several factors:

  • Flesch Reading Ease: Measures how easily readers can understand the text
  • Sentence complexity: Analyzes sentence structure and length
  • Passive voice usage: Measures usage of passive voice constructions
  • Jargon density: Detects technical jargon and specialized terminology

A higher score indicates more readable, clear documentation that follows best practices.