💬 Discussion: Improving User Experience of the Python Project Template

[ecarrenolozano]

Purpose of This Discussion

This discussion aims to gather community feedback to improve the overall user experience of the python-project template. The repository provides a scaffold for new Python projects, including documentation, testing, version management, and code-quality automation. While it offers a solid baseline, there is room to enhance usability, clarity, and developer experience.

Your feedback will help us:

• Identify pain points encountered when using the template.
• Clarify which features are most valuable and which require refinement.
• Understand what is missing for real-world use cases.
• Prioritize improvements by defining well-scoped Issues based on community input.

---

Key Questions for Discussion

1. Template Usability

• Is the current project structure intuitive?
• Were there parts of the scaffold that felt unnecessary or overly complex?
• Are any steps of the setup process confusing, especially for first-time users?

2. Documentation & Onboarding

• Is the generated documentation structure adequate?
• What improvements could make onboarding smoother for new developers?
• Do you see any missing information in the README or the cookiecutter prompts?

3. Tooling & Automation

• Are the pre-configured tools (pre-commit, pytest, bump2version, MkDocs, etc.) sufficient for your workflows?
• Should the template include additional tools (e.g., mypy, Ruff, GitHub Actions workflows, CI pipelines)?
• Are there tools currently included that you would prefer to disable by default?

4. Extensibility & Flexibility

• Does the template support a wide enough range of project types (research tools, libraries, data processing, applications)
• Would you prefer more opinionated defaults or a more minimal scaffold?
• Are there architecture patterns (e.g., Hexagonal Architecture, plugin systems) that you would like the template to consider supporting?

5. Missing Features

• What capabilities do you think the template should add?
• Are there sections of modern Python project best practices that are not represented?

---

How We Will Use Your Feedback

After gathering input from this discussion, we will:

1. Consolidate suggestions into well-defined Issues.
2. Prioritize improvements based on impact and community demand.
3. Propose roadmap items for future template versions.
4. Iterate on the template to ensure a consistent and high-quality development experience.

Your insights are highly valuable. Please feel free to share detailed examples, challenges you encountered, or features you consider essential in a Python project scaffold.

We welcome all contributions — from beginners to experienced maintainers.

---

Thank You

Thank you in advance for helping us evolve the template. Your perspective will directly shape the next versions and help the broader community benefit from a more robust and accessible Python project starter.

[ecarrenolozano]

Hi dear Saezlab members,

This is my feedback on the current iteration of this template:

1. Context of Use

I used this template to create two Python libraries for Saezlab. Those projects include data ingestion, processing pipeline and CLI scripts.

I have moderated with Python project templates and have used Cookiecutter in the past.

2. Setup & Onboarding Experience

The setup process worked overall, but a few areas were confusing:

• Some Cookiecutter prompts were not self explanatory (e.g., project_slug, what does it mean this?). The examples guide me in some way, but it could be great if this is included in the documentation.
• New users may not know why pre-commit runs immediately after the first commit.
• When performing the initial commit —before adding any code — pre-commit reported errors related to the pyproject.toml file. After repeatedly running git add . && pre-commit, the errors disappeared. It would be useful to review this behavior or provide guidance to avoid confusion during the initial setup.

3. Project Structure

The layout is clean, but I found a few limitations:

• The default src/{{project_slug}}/ folder is fine, but a separate notebooks/ or examples/ directory would help research workflows.
• A configs/ directory would help for projects that rely on configuration files.

4. Documentation

The MkDocs structure is helpful, but:

• The initial documentation is too minimal; adding basic sections (installation, minimal example, development guidelines) would make onboarding smoother.
• The autogenerated README feels generic and could be more descriptive.
• No example of how to run the tests or how to build the docs is included.
• There is not documentation about how to configure the gh-pages to load the already made static webpage.

5. Tooling & Automation

• Include a default GitHub Actions workflow for running tests on pull requests.

5. Pain Points

• The template is quite heavy for very small projects.

6. Feature Requests

• Provide optional configurations for different project types (library, CLI tool, scientific analysis, ML pipeline).
• Allow configuration presets via Cookiecutter (e.g., “minimal mode”, “full mode”).

7. Overall Impression

• Overall Rate: 4/5