docs: improve user README and add project logo - #15
Conversation
There was a problem hiding this comment.
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.
| Default output directory name: `outputs`. | ||
|
|
||
| Layout rules: | ||
| When the input is a single file, outputs are written next to that file: |
There was a problem hiding this comment.
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.
| 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: |
| Each segment includes text, start/end timestamps, language metadata, optional | ||
| speaker metadata, and token timing when available. `source_media` includes the |
There was a problem hiding this comment.
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.
| 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 |
Summary
easrworkflows.docs/development.md.docs/assets/asr-logo.pngand display it at the top of README.Test Plan
git diff --checkuv run --python 3.14 easr --helpPYTHONPATH=src uv run --python 3.14 python -m unittest discover -s tests -p 'test_*.py'(157 tests)Notes
claudeCLI was not installed.