Issue template form — alternate take #4308
Conversation
|
Documentation previews: |
This comment was marked as resolved.
This comment was marked as resolved.
There was a problem hiding this comment.
Just left two comments for your consideration. Thanks for setting this up, @joepeeples!
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Hello! This form will create an issue that the Security docs team will triage and prioritize. Please do not add any labels to your issue — we'll take care of that. |
There was a problem hiding this comment.
I think the DE team is the only one that needs the extra/custom labels so they can track doc issues on their project board. One option for reducing the increasingly large label load is to agree on a set of labels that we can both use for tracking purposes.
There was a problem hiding this comment.
I'm actually thinking maybe we just omit the sentence about labels. That was originally copied from the Obs docs team's form, where they're using automation to auto-label issues based on responses throughout the form (and maybe manually adding labels interferes with that?).
We're not planning to implement that, at least not for our first iteration, so we'll end up manually adding and adjusting labels regardless. I don't see why we should discourage anyone if they want to try to help us label an issue. @jmikell821 WDYT?
| Why: This feature will make X, Y, and Z easier for the user. | ||
| How: The user navigates to *Foo* → *Bar*, then clicks the *Wow* button. | ||
| validations: | ||
| required: true |
There was a problem hiding this comment.
Would be a good place to ask whether there's an API doc impact?
I'm also still unsure whether we should put a checkbox here, or add another text field. I'm leaning towards a text field so devs have the opportunity to add more detail, if they have more to share. @natasha-moore-elastic what are your thoughts here?
| required: true | |
| required: true | |
| - type: textarea | |
| id: description | |
| attributes: | |
| label: API docs impact | |
| description: Describe what needs to be documented and provide example responses. What parameters and endpoints need to be documented? | |
| placeholder: | | |
| What: We're introducing new endpoint A. | |
| Why: Users can send a request to endpoint A to use feature A. | |
| How: The user provides the specific information in the request | |
| validations: | |
| required: true |
There was a problem hiding this comment.
I agree, a text field is more flexible for additional info. Minor edit to suggestion above: label: API docs impact
There was a problem hiding this comment.
Actually, once I committed the suggestion and looked at the preview, it seems like maybe this should go lower in the order of fields, maybe between "Feature differences" and "Prerequisites...." IMO it kind of sticks out toward the top. It's a required field so the submitter can't overlook it even if it's lower.
There was a problem hiding this comment.
Moved in 5dc55c8 to see how it looks in the preview; we can revert or relocate elsewhere if needed.
There was a problem hiding this comment.
Agree with having a text field rather than a checkbox so that more info can be provided.
I can't seem to add a suggestion for line 24. I'd maybe update the description to something slightly more specific, like:
Provide endpoint and parameter descriptions, and requests and response examples.
There was a problem hiding this comment.
I think you can't comment on the suggestion above because I already committed it, then moved it to a different part of the file. The description for API docs is now line 82; you should be able to comment on that in the diff tab, @natasha-moore-elastic.
Co-authored-by: Nastasha Solomon <[email protected]>
Co-authored-by: natasha-moore-elastic <[email protected]> Co-authored-by: Benjamin Ironside Goldstein <[email protected]>
Contributes to #4229 with an alternative version of #4301. This version combines some fields to streamline the flow, and makes a few other assorted adjustments.
Preview:
https://github.com/elastic/security-docs/blob/issue-template-form-redux/.github/ISSUE_TEMPLATE/internal-docs-request.yaml
Summary of edits
Consolidate:
Background & resources: Changed the placeholder text into default text, so it persists when you click on the field. I really don't want people to forget to include any of these bits of info, which they might if the text disappears when they start typing.
Remove: Acceptance Test Criteria. This section has always been confusing to me, and historically I don't think people follow this format when creating issues. It also seems like a misnomer to call it "test criteria" since we're documenting, not testing. I think this section was asking for the feature's typical workflows, which could be part of the main Description's prompt.
Release timelines: We need to know both the Stack release and the serverless release timelines, so added a field just for serverless release.