# Make and Document a Plan

By leveraging [GitHub issues](https://github.com/features/issues) to document both broad needs and specific tasks, and organizing them within a project board, you can streamline project management, enhance clarity, foster collaborative problem-solving, and is also a good approach when asking for help. This approach ensures that each aspect of your project is actionable, trackable, and aligned with your overarching goals.

<!-- ## Goal
By the end of this exercise, you'll learn to express your project needs or user needs using a structured approach inspired by user stories. This will help you prioritize aspects of your project and translate needs into specific software requirements. -->

<!-- ## Overview
Remember, this program includes guidelines on FAIR principles and open collaboration. The exercises provided offer a mini roadmap to follow during your project.
-->
<!-- ## 1. Create a Simple Roadmap
Craft a straightforward roadmap consisting of key milestones. Based on your learnings and reflections on the Coderefinery workshop, define what priorities and aspects are important in the form of a roadmap.

**Tip:** Share your roadmap as an issue in your repository for feedback. Include relevant aspects from code writing to publishing.

**Example Roadmap:**

## Roadmap Milestones
- Refactor my codebase; integrate tests
- Develop a documentation website with tutorials
- Make codebase accessible for an upcoming course
- Launch a prototype for external testing by mid-2023
- Optimize code for cluster execution
- Aim to publish a paper by end of 2023

## 2. Define Your Needs with a User Story Template
**Instructions:** Create at least one user story following the template below. Optionally, craft additional stories specific to your project, covering relevant areas not discussed in the workshop. You can create as many stories as you need.

### Template Structure

As a [specific role],
I need [specific workshop topic]
because [specific reason].
I plan to [specific application method],
enabling [specific expected outcome].

### Specificity Guidelines
1. **Role:** Define your role precisely within your project's context.
2. **Workshop Topic:** Pick a CodeRefinery topic (a story) directly linked to your project's challenge.
3. **Reason:** Clearly state why this topic is a priority.
4. **Application Method:** Describe how you'll apply this topic practically.
5. **Expected Outcome:** Specify the improvement or result you anticipate.

### Example

As a PhD student developing machine learning models,
I need software testing practices,
because I'm struggling with model reliability after changes.
I plan to integrate pytest for automated testing workflows,
enabling me to refactor models confidently without fearing regressions.

## 3. Organize with a Project Board
A project board helps manage tasks, prioritize them, and keep track of who is doing what. It captures project status, priorities, and individual responsibilities.

**Instructions:** [Create a project board on GitHub](https://docs.github.com/en/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project) or a similar platform. -->

## Breakdown Needs into Issues/Tasks
<!-- **Creativity Required:** Transforming wishes into specific tasks is challenging. Use your project board to facilitate this process, leveraging GitHub issues not only to define broader problems or enhancements but also to specify tasks.
-->
### Distinguishing Issues from Tasks
- **Issues** can encompass broader problems, enhancements, feature requests, or questions. They may require discussion, investigation, or further breakdown into more actionable items.
- **Tasks** are specific, actionable items that contribute directly to resolving an issue. They are the discrete steps needed to complete a broader issue.

### Using GitHub Issues for Both Issues and Tasks
- **Create Issues for Broad Needs:** Begin by documenting broad needs, problems, or questions as issues. Provide a clear title and detailed description to ensure understandability.
- **Example:** "Improve project documentation to facilitate new contributor onboarding."

- **Define Tasks Within Issues:** For each broad issue, you can also use GitHub issues to define specific tasks. This can be achieved by creating separate issues for each task linked to the main issue or by using task lists within a single issue.
- **Example Task Issue:** "Create a 'Getting Started' guide for new contributors."
- **Task List in Issue:** Use GitHub's task list feature in the issue description to outline steps or tasks. This keeps everything related to a single issue in one place.

        - [ ] Review current documentation for completeness.
        - [ ] Identify key areas lacking information.
        - [ ] Draft 'Getting Started' guide sections.
        - [ ] Review and revise the guide with the team.

You can go further and take advantage of [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository).

### Organizing and Prioritizing Tasks
- **Labels and Milestones:** Utilize labels to categorize tasks by type (e.g., bug, enhancement) and use milestones to group tasks related to specific project phases or goals.
- **Assignees:** Assign tasks to specific team members to clarify responsibilities. If working solo, assigning tasks to yourself can help keep track of your to-do list.

<!-- ### Monitoring Progress
- **Progress Tracking:** Use the project board to track the progress of tasks across different stages (e.g., To Do, In Progress, Done).
- **Review and Adjust:** Regularly review the board and issues to adjust priorities, reassign tasks as needed, and close issues that have been resolved. -->

## Notes on how to open issues
### Raising an Issue:
- **Search for Existing Issues**: Before creating a new issue, search existing ones to avoid duplicates and contribute to ongoing discussions. Reference: [GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
- **Follow the Issue Template**: If the project has an issue template, ensure you fill it out completely to provide all necessary information. Reference: [GitLab - Issue Templates](https://docs.gitlab.com/ee/user/project/description_templates.html)
- **Provide Clear Steps to Reproduce**: Detail the steps required to reproduce the issue, along with any relevant code snippets or screenshots. Reference: [GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
- **Include Environment Details**: Mention the environment (e.g., operating system, browser version) in which the issue occurs, if applicable. Reference: [GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
- **Be Courteous and Respectful**: Maintain a respectful tone and avoid using all caps or offensive language when describing the issue. Reference: [Stack Overflow - How do I ask a good question?](https://stackoverflow.com/help/how-to-ask)

## References
[eScience Center Software Management Plan Template](https://www.esciencecenter.nl/wp-content/uploads/2021/07/SMP2021-v1.057.pdf)
[GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
[Stack Overflow - How do I ask a good question?](https://stackoverflow.com/help/how-to-ask)
[GitLab - Submitting a Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
[GitHub Community Guidelines](https://docs.github.com/en/github/site-policy/github-community-guidelines)
[Stack Overflow - How do I ask a good question?](https://stackoverflow.com/help/how-to-ask)

[GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
[GitLab - Issue Templates](https://docs.gitlab.com/ee/user/project/description_templates.html)
[GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
[GitHub - Creating an Issue](https://github.com/rstudio/rstudio/wiki/Writing-Good-Bug-Reports)
[Stack Overflow - How do I ask a good question?](https://stackoverflow.com/help/how-to-ask)