TWE: Create Template Issue: Create Research Template Issue, Testing Guidance

[ExperimentsInHonesty]

Overview

We need to create a template issue for TWE: Research: Research Issue Templates: Test so that we have a consistent, transparent, defined, and self-supporting structure for people creating testing issues.

Action Items

Customize this issue

• Customize this issue by adding the Name of Issue Template.
  • Note: An issue template's name is different from the issue title created from the template.
  • Search for [Replace NAME OF ISSUE TEMPLATE] by using the browser search (Mac: ⌘+F; PC: Ctrl+F)
  • Replace the keyword string (including text and the brackets) below with the name of your issue template according to the template naming convention: TWE: Role: Direct object: Action verb
    • The role is the primary owner of the issue template (e.g., Research, Design, Product)
    • Direct object should be the item that we're updating or working on (e.g., Wiki, Interviews, Roadmap)
    • Action verb should be the main descriptor of the action items (e.g., Update, Create, Transcribe)

Customize the issue settings (located in right sidebar)

Change the issue settings to ensure the issue is properly categorized and easy to manage.

• Under Assignees, assign yourself.
• Under Projects, choose gear, choose Repository, and choose TWE Project Management.
• Add the milestone: Project Management
• Add a feature label specific to what the template is related to, if available. If not clear what you should use, ask product.

Customize template draft

Create a draft of new template, which will be known as our "draft".

• Copy resource 1.01 Content to copy for draft to a new comment on this issue.
• In your draft, fill out the top part (called front matter) with the following information. See resource 1.02 Front Matter Resources section below for definitions and examples.
  • Name
  • About
  • Title
  • Labels
• Define any Dependencies (or remove the dependency section if there is no dependency)
• Customize the Overview section
• Fill out the Action Items section (in your draft) by defining the steps that are required to be done, keeping the following in mind:
  • The person working on this issue might be new to the org, so the issue should be able to be worked on without any prior knowledge
  • If the person needs to add links, or put documents in specific locations, the place where they can do that action must be linked in the resources section
    • The links in the resources section provided by the issue creator should be in the same order as the Action Items
    • Refer to resource 1.03 Example Action Items for Finding Wiki Page and Template for an example of how to write clear instructions that avoid compound steps (steps within a step).
  • Number each resource in the order each resource appears in the Action Items
    • Group resources into numbers and decimals (e.g., Resource 1.01, Resource 2.01)
    • Group the resources based on whether they are available when making the issues or they need to be created from this issue
      • If the resource is available, then group it under the Resources for creating this issue section (e.g., Resource 1.01, Resource 1.02, Resource 1.03)
      • If the resource will be delivered or created from this issue, then group it under the Resource links gathered during the making of this issue section (e.g., Resource 2.01, Resource 2.02, Resource 2.03)
• If documents or folders (sheets, docs, presentations, dashboard, etc.) will be created, find the document template that should be used by checking resource 1.04 WIKI Templates by role pages.
  • If there is a template
    • Add a link to the template into the #### Resources for creating this issue section of your draft
  • If there is no template yet
    • Put a placeholder into the #### Resources for creating this issue section of the draft [TWE: Template Issue: [Role]: [Replace ACTION VERB][Replace DIRECT OBJECT]
• Get sign-off by Product on the draft
• Create the template issue on the repo if needed
• Add the link to the new issue template once created to resource 2.01. Find by clicking on the Get started button to the right of the new template listed on new issue page
• Update the appropriate place in the wiki for your template (see resources section)

Resources/Instructions

Resources for creating this issue

• 1.01 Content to copy for draft

Draft of template issue for `Create Research Template Issue, Testing Guidance`
---
**name:** TWE: Template Issue: [Replace ROLE]: [Replace ACTION VERB][Replace DIRECT OBJECT]
**about:** This issue helps you structure your template issue to be consistent with our other template issues in [Replace DIRECT OBJECT]
** title:** TWE: [Replace ROLE]: [Replace DIRECT OBJECT]: [Replace ACTION VERB]
**labels:** 'feature: board / google drive / tools, feature: missing, milestone: missing, role: missing, size: missing', 'Participant Type: missing', 'complexity: missing'
**assignees:**

---
#### Instructions for creating this issue
The person who creates this issue should use these links to add links to the resources section and customize this issue
- Customize the issue
    - [ ] Copy and paste entire template text in this issue into text editor (ie., "TextEdit" on _Mac_, "Wordpad" on _PC_)
    - Use Find/Replace (**Mac:** ⌘+F or **PC**: Ctrl+F) to search for and replace the keyword strings (including text and the brackets) below with the appropriate values 
    - [ ] Search for `[Replace`
    - [ ] Replace with whatever the keyword or information is asking for.
- Customize the issue settings (located in right sidebar)
    - [ ] Under Labels, add labels for any labels identified as missing
    - [ ] Remove the corresponding missing labels
    - [ ] Under Projects, choose gear, choose "Repository," and choose TWE Project Management.
    - [ ] Add the milestone: [Replace MILESTONE]
    - [ ] Add a feature label specific to what the template is related to, if available. If not clear what you should use, ask product.
- Customize dependencies 
    - [ ] If no dependencies, delete dependency section
    - [ ] If dependencies, add the dependencies (any issue or reason that would prevent the action items from being completed)
- Remove this section.
    - [ ] Delete this section when all the checkboxes above are complete (i.e., the issue assignee will never see this part)

### Dependencies

### Overview
We need to [Replace ACTION VERB] [Replace DIRECT OBJECT] for [Replace REASON].

### Action Items
A STEP BY STEP LIST OF ALL THE TASK ITEMS THAT YOU CAN THINK OF NOW EXAMPLES INCLUDE: Research, reporting, coding, etc.

### Resources
#### Resources for creating this issue
1.01
1.02

#### Resources gathered during the completion of this issue
2.01
2.02

• 1.02 Front Matter Resources

  Front Matter Fields and Meaning

  • name: (name that appear on the new issue tab)
  • about: (is the description that appears next to the issue template on the new issue tab)
  • title: (the title that appears when the issue is created. User then customizes this title for their issue)
    • Use the naming convention: TWE: Role: Direct object: Action verb
    • If more than one word should go into the direct object spot, use multiple square brackets with the keyword (see example below)
  • labels: (choose the labels that will be the same each time, and choose missing labels for the ones that depend on content)
  • assignees:
  Front Matter Field Example

  • name: 'TWE: Template Issue: Research: Create Roadmap'
  • about: This issue helps you structure your template issue to be consistent with our other template issues in roadmap
  • title: 'TWE: Research: IS[Replace YY]: RP[Replace 000]: [Replace TYPE OF PARTICIPANT] [Replace TYPE OF RESEARCH METHOD]: Roadmap : Create'
  • labels: 'feature: research', 'feature: roadmap', 'milestone: missing', 'role: UI/UX research', 'Participant Type: missing', 'Research 000: missing', 'complexity: missing'
  • 'size: 0.50pt'
  • assignees: ''

• 1.03 Example Action Items for Finding Wiki Page and Template

  Example Action Items

  ### Action Items
  - Customize wiki page
       - [ ] Go to link 1.01 Internship Wiki, Join the team page
       - [ ] Find wiki page for this issue by looking at role pages.
       - [ ] Copy the link for the wiki page.
       - [ ] Add the link to Resource 2.01
          - [ ] Add the name of the link in square brackets
          - [ ] Add the URL in parenthesis without a space between the square bracket and parenthesis
  - Customize document template.
      - [ ] Go to link 1.02 Design Process Overview
      - [ ] Find document template that should be used in this issue.
      - [ ] Copy the link for the template.
      - [ ] Add the link to Resource 2.02
          - [ ] Add the name of the link in square brackets
          - [ ] Add the URL in parenthesis without a space between the square bracket and parenthesis
  

  Example Resource Lists

  ### Resources for creating this issue
  1.01. [Internship Wiki, Join the team page](https://github.com/hackforla/internship/wiki/Joining-the-Team)
  1.02. [Design Process Overview](https://github.com/hackforla/internship/wiki/Design-Process-Overview)
  
  ### Resource links gathered during the making of this issue
  2.01. [Wiki page for [Replace TYPE OF ROLE]]
  2.02. [TWE: Template: [Replace NAME OF TEMPLATE]]
  

• 1.04 WIKI Templates by role pages

  • TWE: WIKI: UX Research Guides Templates
  • Design
  • Product
  • [Business Analyst / Data Science]
  • [Software Engineer]
  • [Marketing]
  • default document templates, in case you don't have one yet, can be found on the Design Process Overview page

Resources gathered during the completion of this issue

• 2.01 Research: Test: Issue Template

[ExperimentsInHonesty]

---

Draft of template issue for Create Research Template Issue, Testing Guidance

name: TWE: Template Issue: Research: Test: Issue Template
about: This issue takes the draft of an issue template and provides a checklist to see if it's ready for deployment, and if not, give feedback until it is ready to be made available to use.
** title:** Research: Test: Issue Template: [Replace with TEMPLATE NAME]
labels: feature: missing, feature: test a template (step 2a), status: template testing, milestone: missing, role: UI/UX research, size: 3pt', 'Participant Type: TWE Team Member', 'complexity: good first issue', 'feature: research', 'time sensitive'
assignees:

---

Instructions for creating this issue

The person who creates this issue should use these links to add links to the resources section and customize this issue

• Customize the issue
  • Copy and paste entire template text in this issue into text editor (ie., "TextEdit" on Mac, "Wordpad" on PC)
  • Use Find/Replace (Mac: ⌘+F or PC: Ctrl+F) to search for and replace the keyword strings (including text and the brackets) below with what the keyword or information is asking for (which will be in the create template issue this issue is testing.
  • Search for [Replace with LINK TO TEMPLATE DRAFT ISSUE COMMENT]
  • Search for [Replace with DEFAULT TITLE THAT ISSUE TEMPLATE WILL HAVE]
  • Search for [Replace DIRECT OBJECT]
  • Search for [Replace with NAME OF TEMPLATE]
  • Copy and paste the edited template from text editor back into this GitHub Issue, replacing all original text
  • Re-check all the checkboxes above after copying and pasting the edited template
  • Close the text editor
• Customize the issue settings (located in right sidebar)
  • Under Labels, add the feature that matches which template you are testing (e.g., if you were testing the roadmap template you would choose feature: roadmap)
  • Add to the project board, by, choosing the gear next to Projects, choose "Repository," and choose TWE Project Management
  • Add the milestone: 06.00 Research Guidance
  • Remove the label Milestone: missing
• Customize dependencies
  • If no dependencies, delete dependency section
  • If dependencies, add the dependencies (any issue or reason that would prevent the action items from being completed)
• Remove this section.
  • Delete this section when all the checkboxes above are complete (i.e., the issue assignee will never see this part)
  • Depending on your role, please do the following:
    • Research Lead: put this issue into the prioritized backlog
    • Team member: add the ready for research lead label

Dependencies

[Replace with the link to the issue template issue this issue will review, when its issue template is ready for testing]

Overview

We need to test the [Replace DIRECT OBJECT] Issue Template so that researchers can start making [Replace DIRECT OBJECT] issues on/for the various research plans/tasks

Details

We expect that the template you are testing will need some improvement and the fact that you don't know much about the project is a benefit here, because it's likely that the person making the template can overlook something that they already know how to do, but should be fully explained in the template so that people can do the work independently.

Action Items

• Go to the draft issue template in a comment on the issue where the draft you are testing is being created in Resource 1.01
• Copy the draft
  • Clicking on three dots
  • Choose edit
  • Select the contents (Use Select All Mac: ⌘+A or PC: Ctrl+A)
  • Copy the contents (Use Copy Mac: ⌘+C or PC: Ctrl+C)
• Create the new issue
  • Open a new blank issue template (Resource 1.02)
• Use the template to customize the issue
  • Paste the draft into the new issue body
  • Replace the title with the following text

    `[TEST]` 
    

  • Add the title from Resource 1.03 after the text: [TEST]. This part is the title that would have been provided if the issue was made from a template instead of this testing process.
  • Submit the new issue
• Add Labels to the new issue
  • Locate the labels associated with the template to be tested.
    Example: See the highlighted section

    

  • Add all the labels associated with the template to be tested in the new issue you just created
    • Under Labels, choose gear
    • Select each label you previously located
  • Add status: template testing (step 2a) label
• Add new issue to Project Board
  • Under Projects, choose gear , choose Repository, and choose Program Management
  • refresh the browser tab
  • Under program management, choose the down arrow and change the selection from New Issue Approval to In Progress
• Assign yourself the issue
  • Under Assignees, Choose No one - assign yourself
• Use the new issue to test the template
  • Follow the instructions in the new issue. Your goal is to test that the template is sufficient for creating the issue and working on it, so for the purposes of this test, you are the creator of the issue and the assignee.
  • If you have any questions about the instructions in this issue, leave a comment below and move this issue to the Questions column add ready for research lead label
  • When you have question or suggestions about the instructions in the new issue issue you are using to test the template, please:
    • leave comments in that new issue, @ messaging the person who made the template in your comment
    • move it to the Questions column
    • add ready for research lead label
    • @ message the person who made the template in Slack with a link to your comment.
  • Review changes to the template made by author and repeat your review process until you are satisfied that it's ready for deployment
    • Leave a comment on the template issue and the new issue you created with your sign-off (@ messaging both the template author and the Research Lead)
    • Add the issues to the next Research team agenda (Resource 1.04) and @ messaging both the template author and the Research Lead via the team Slack channel with a link to the issue comments)

Research lead action items

• review the template again
  • if changes are needed, send back to author with notes
  • if no changes are needed, deploy template, close issues.
    • Add link to the finished template to Resource 2.01

Resources

Resources for creating this issue

• 1.01 [Replace with LINK TO TEMPLATE DRAFT ISSUE COMMENT]
• 1.02 Blank issue template
• 1.03 [Replace with DEFAULT TITLE THAT ISSUE TEMPLATE WILL HAVE]
• 1.04 TWE: UX Research Meeting Agenda #62

Resources gathered during the completion of this issue

• 2.01 [Replace with NAME OF TEMPLATE]

[ExperimentsInHonesty]

@pandanista @sunannie27 - @KC-skc and I finished making this template, and now we need you to test it. We should probably do it as a group. I suggest next Monday.

[pandanista]

• Testing this template in Research: Test: Issue Template: Consent Document Creation #555.

• Feedback for the first half of the template is in this comment.

[ExperimentsInHonesty]

• process all the comments
• Turn into a template.
  • Research: Test: Issue Template
• Add to the WIKI

@pandanista

More steps?

Given that this such a crucial template, I am ok with us doing additional testing, but on a normal create template issue, according to the checkboxes above, we would close this issue at this point (because the template is live). If we decide templates should get a second test after they are live, we should revise the checkboxes on the create a new template, template issue.

• Determine next steps
  • We would create a testing issue, using the link above for a test of X template, customizing enough so that they know what they are working on.
    • I thought we were going to have Sandy test it on an issue she was going to work on, but I am not sure which template that was.
  • Assign the new testing issue to the person
  • If they have comments, we would do more revisions to the template

[pandanista]

• We need to add instructions to ask the assignee/tester to include the labels of testing issue to the testing template.
  • For example, the testing issue has labels that need to be added to the testing issue
• See the verbiage below:
  • Add the labels of the testing issue you just created

[ExperimentsInHonesty]

We do need to add a section for adding the labels to the test issue. Add the instructions between these two checkboxes

• Submit the new issue
• Under Projects, choose gear , choose Repository, and choose Program Management

[pandanista]

• Please see the revised instructions for adding labels associated with the template to be tested below:

  • Locate the labels associated with the template to be tested.
    Example: See the highlighted section

    

  • Add all the labels associated with the template to be tested in the new issue you just created
    • In the right side panel, under Labels, choose gear
    • Select each label you previously located
  • Add status: template testing (step 2b) label

• Feel free to edit them or move them into the testing template above.

[ExperimentsInHonesty]

The template has been deployed.

[sunannie27]

I've signed off on issue 555