SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsreadme-writer

readme-writer

General & other

View repository

Updated 10-15 23:57

About this skill

Readability and README Writing

Two jobs. The common one: measure and improve reading level in any prose — a doc, an email, a proposal, a spec, a plan. The narrower one: structure a README.

Always Measure — Never Estimate

Syllable counts cannot be eyeballed accurately across a document. Reporting a Flesch-Kincaid score without running the script is guessing. Run it.

cat FILE | ruby scripts/flesch_kincaid.rb

Works on any text, not just markdown — pipe in an email draft, a section of a doc, a paragraph pasted into a heredoc.

Target: grade level 11 or below. Technical terms inflate the score, and that's fine — the goal is to keep the surrounding prose clear so the technical content stays accessible.

Revise, then re-measure. Focus revision on:

  • Shortening sentences (not dumbing down terminology)
  • Replacing complex connectors with simple ones
  • Breaking multi-clause sentences into two

Report the before and after scores.

Vocabulary Coverage

Many readers of technical writing are not native English speakers.

cat FILE | ruby scripts/vocabulary_profiler.rb

Aim to raise the percentage of words in the top 1000 most common English words. Technical terms lower this number — expected. Keep the non-technical words simple.

Do:

  • Use active voice
  • Keep noun phrases short and direct
  • Limit embedded clauses to one level of nesting
  • Use simple "if/then" conditionals
  • Make logical connections explicit with transition words (however, therefore, because)
  • Spread information across multiple sentences when needed

Don't:

  • Stack multiple modifiers before nouns ("the recently revised standardized testing protocol")
  • Rely on mixed or inverted conditionals ("Had she known...")
  • Expect readers to infer relationships between ideas
  • Pack too many new concepts into a single sentence
  • Assume shared knowledge of idioms or cultural references

Flow and Transitions

  • Start with concepts, then details. Give readers the "why" before the "how"
  • Add transitions between major sections so the piece reads as a narrative, not a list of disconnected blocks
  • Create logical progression from high-level to detailed

README Structure

When the document is specifically a README, it flows through these sections:

  1. What and why — what the package does and why it matters (the "what's in it for me")
  2. Install and use — how to get started quickly
  3. Configuration — common options and methods
  4. Contributing — how to contribute, or a pointer to CONTRIBUTING.md. Notes on the build environment and portability
  5. Project layout — unusual top-level directories or files, hints for navigating the source

Formatting

Use GitHub-flavored callout blocks to highlight important information:

[!CAUTION] [!IMPORTANT] [!NOTE] [!TIP] [!WARNING]

  • Use bold for key concepts on first introduction
  • Use code for commands, filenames, config keys, and values
  • Use concrete, descriptive names for examples ("Invoice Approval" not "Example 1")

Quality Checklist

  • Flesch-Kincaid grade level measured with the script, at or below 11
  • Vocabulary coverage measured; non-technical words kept simple
  • Each section flows naturally into the next
  • Key concepts are bolded on first use
  • Examples use real scenario names, not generic placeholders
  • No corporate buzzwords (comprehensive, robust, seamless, leverage, utilize)
  • Terminology is consistent throughout (same word for same concept)
  • Acronyms and specialized terms are defined on first use
  • Active voice is used wherever possible

Bibliography