Skip to content

docs: improve user README and add project logo - #15

Merged
morehardy merged 1 commit into
mainfrom
codex/readme-user-guide-logo
May 26, 2026
Merged

docs: improve user README and add project logo#15
morehardy merged 1 commit into
mainfrom
codex/readme-user-guide-logo

Conversation

@morehardy

Copy link
Copy Markdown
Owner

Summary

  • Refocus README around first-time user onboarding and common easr workflows.
  • Move developer, build, test, and PyPI release guidance into docs/development.md.
  • Add the project logo under docs/assets/asr-logo.png and display it at the top of README.

Test Plan

  • git diff --check
  • Local README/development link resolver script
  • uv run --python 3.14 easr --help
  • PYTHONPATH=src uv run --python 3.14 python -m unittest discover -s tests -p 'test_*.py' (157 tests)

Notes

  • External implementation audit was not run because the local claude CLI was not installed.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request restructures the project documentation by refactoring the README.md into a concise user-facing guide and moving developer-specific workflows to a new docs/development.md file. The updated README.md features a simplified layout, including a new logo, a clearer description of output files, and a table for CLI options. Feedback from the review identified a need to clarify the default output directory behavior for single files and pointed out a contradiction regarding speaker metadata in the JSON documentation, which is not yet implemented.

Comment thread README.md
Default output directory name: `outputs`.

Layout rules:
When the input is a single file, outputs are written next to that file:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The description "written next to that file" is slightly ambiguous because the example below shows that the outputs are actually placed within an "outputs/" subdirectory. Clarifying this in the text would improve the user's understanding of the default behavior.

Suggested change
When the input is a single file, outputs are written next to that file:
When the input is a single file, outputs are written to the outputs/ directory next to that file:

Comment thread README.md
Comment on lines +183 to +184
Each segment includes text, start/end timestamps, language metadata, optional
speaker metadata, and token timing when available. `source_media` includes the

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This section mentions "optional speaker metadata" as part of the segment data in the JSON output. However, the "Current scope" (line 18) and "Current Limitations" (line 282) sections explicitly state that speaker diarization is not yet implemented. Removing this reference prevents user confusion regarding available features.

Suggested change
Each segment includes text, start/end timestamps, language metadata, optional
speaker metadata, and token timing when available. `source_media` includes the
Each segment includes text, start/end timestamps, language metadata, and token timing when available. source_media includes the

@morehardy
morehardy merged commit b77713f into main May 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant