Improve README with detailed usage examples and clearer documentation #2
Description
Description
The current README provides a brief overview of the project but lacks detailed, practical usage examples. New users and contributors may find it difficult to understand how to use the utilities without exploring the source code.
Enhancing the README with clear explanations and examples will improve usability, onboarding, and overall developer experience.
Current limitations
- README does not include concrete code examples
- No sample inputs / outputs are shown
- Usage of individual utilities is not clearly explained
- Project structure and purpose could be clearer for first-time users
Proposed improvements
Contributors can help by adding or improving the following sections:
1. Usage examples
- Show how to import utilities from
textutils - Provide examples for each major function (e.g., cleaner, analyzer)
- Include sample inputs and outputs
example:
from textutils.cleaner import clean_text
clean_text(" Hello WORLD ")
# Output: "hello world"
2. Explain project purpose
- Clarify what problem the project solves
- Mention that it is an educational / learning-focused Python package
- Briefly explain what concepts it demonstrates (modules, packaging, testing)
3. Improve setup instructions
- How to install the package locally
- How to run tests
- How to use editable installs (
pip install -e .)
4. Improve readability
- Use clear headings and sections
- Add short descriptions under each section
- Keep examples concise and beginner-friendly
Acceptance criteria
- README includes clear, runnable examples
- All major utilities are documented
- Setup and usage instructions are easy to follow
- Documentation changes do not affect code behavior
- README is clear for both beginners and contributors