How to Write an Issue for an Engineer - hackforla/311-data GitHub Wiki

General Guidelines

  1. Provide a one-line overview: Begin by providing a one-line overview of the issue. This should be a brief and clear summary of the problem you are trying to solve or the task you need the engineer to perform.
  2. Specify the workspace requirements: Specify any requirements for the workspace, such as the tools, software, and data needed to complete the project. This can include specific versions of software or libraries that are required to run the code. Be clear about what is needed and any constraints that must be taken into account.
  3. Provide links to workspaces: If there are existing workspaces that are relevant to the issue, provide links to those workspaces. This can help the engineer understand the problem and identify potential solutions.
  4. Break the issue down into manageable parts: Break the issue down into manageable parts or tasks, each with its own set of steps to work on the code. This can help the engineer understand the scope of the project and focus their efforts on specific areas.
  5. Provide steps for each part of the issue: For each part of the issue, provide clear and specific steps for working on the code. This can include specifying which files to modify, which functions or methods to use, or any other relevant details. Be sure to include any necessary guidance or resources.
  6. Be clear about creating a workspace: If the engineer needs to create a new workspace, be clear about the requirements for the workspace and any steps that need to be taken to set it up. This can include specifying the tools or software that need to be installed, or any configuration settings that need to be adjusted.
  7. Specify any security or access requirements: If the workspace needs to be secure or access-restricted, specify the requirements for security and access controls.
  8. Be open to collaboration: Be open to collaboration and feedback from the engineer. Encourage them to ask questions and provide input, and work together to develop the best possible solution.