Skip to content

Latest commit

 

History

History
152 lines (101 loc) · 4.24 KB

source-attribution.md

File metadata and controls

152 lines (101 loc) · 4.24 KB

Source Attribution Guide

This document maps the principles and patterns in this repository to their original sources, showing how we've synthesized best practices from industry leaders.

Primary Sources

1. Command Line Interface Guidelines (clig.dev)

URL: https://clig.dev
Focus: Comprehensive modern CLI design principles

Key Contributions:

  • Human-first design philosophy
  • Composability and modularity principles
  • Progressive disclosure pattern
  • Robustness and error handling guidelines
  • "Abandon a standard when it is demonstrably harmful" philosophy

2. Heroku CLI Style Guide

URL: https://devcenter.heroku.com/articles/cli-style-guide
Focus: Technical implementation and conventions

Key Contributions:

  • "CLI is for humans before machines" principle
  • Naming conventions (topics as plural nouns, commands as verbs)
  • Color usage and terminal detection patterns
  • Output formatting (human vs machine-readable)
  • Flag design preferences over positional arguments

3. Atlassian's 10 Design Principles

URL: https://www.atlassian.com/blog/it-teams/10-design-principles-for-delightful-clis
Focus: User experience and delight

Key Contributions:

  1. Align with established conventions
  2. Build --help into the CLI
  3. Show progress visually
  4. Create a reaction for every action
  5. Craft human-readable error messages
  6. Support skim-readers
  7. Suggest the next best step
  8. Consider your options (prompting)
  9. Provide an easy way out
  10. Flags over args

4. GNU Coding Standards

URL: https://www.gnu.org/prep/standards/standards.html
Focus: Traditional UNIX philosophy and conventions

Key Contributions:

  • Standard options (--help, --version)
  • Exit code conventions
  • Option parsing standards (getopt_long)
  • Device-independence principle
  • Stdout/stderr separation

Principle Mapping

Our Four Core Principles

1. 🎯 Obvious Over Clever

Sources:

  • Atlassian: "Align with established conventions" (#1)
  • clig.dev: "Ease of discovery" and consistency principles
  • GNU: Standard option conventions

2. 💬 Helpful Over Minimal

Sources:

  • Atlassian: "Craft human-readable error messages" (#5), "Suggest the next best step" (#7)
  • clig.dev: "Empathy" principle, comprehensive error handling
  • Heroku: Human-first output philosophy

3. 🔄 Consistent Over Special

Sources:

  • GNU: Uniform option parsing and naming
  • Heroku: Consistent naming conventions
  • clig.dev: "Consistency across programs"

4. 👤 Human-First, Machine-Friendly

Sources:

  • Heroku: "CLI is for humans before machines"
  • clig.dev: Human-first design with machine-readable options
  • Atlassian: Visual progress (#3), skim-reader support (#6)

Pattern Attribution

Command Patterns

  • Subcommands: Git-style (popularized by Git, documented in Heroku guide)
  • Resource-oriented: Kubernetes kubectl pattern
  • Flag preferences: Heroku ("flags over args") and Atlassian (#10)

Error Patterns

  • Structured errors: clig.dev (human-friendly messages)
  • Actionable messages: Atlassian (#5) and clig.dev
  • Exit codes: GNU standards and POSIX conventions

Output Patterns

  • Progress indicators: Atlassian (#3)
  • Color usage: Heroku (with NO_COLOR respect)
  • Format detection: clig.dev and Heroku (TTY detection)

Interactive Patterns

  • Prompting: Atlassian (#8 "Consider your options")
  • Confirmations: clig.dev (dangerous operations)
  • Easy exit: Atlassian (#9)

Usage in Documentation

When citing principles, use this format:

This principle derives from Heroku's "CLI is for humans before machines" philosophy,
combined with clig.dev's emphasis on human-first design.

Or for inline attribution:

### Progress Indicators (via Atlassian #3)

Always show progress for operations lasting more than one second...

License Compliance

All referenced materials are used in accordance with their licenses:

  • clig.dev: Open source guidelines
  • Heroku: Public developer documentation
  • Atlassian: Published blog content
  • GNU: Free documentation license

This attribution guide ensures proper credit while showing how we've synthesized and extended these principles for modern CLI design.