Update issue templates #197
Conversation
Please review my proposed new issue template for a templateer to create a new doctype template.
There was a problem hiding this comment.
Praise: Nice work on this! I think this is great for our purposes at this point in the project!
Chore: Later, when we've built out more of the supporting documentation, we might want to add some introductory text that links to the guides or policies that we want new users to consult before claiming a ticket, such as our contributing guide for templates or any style and formatting guides. It can be there just as a safeguard in case the issue is someone's first exposure to our community and our process. An an example, here's a sample ticket for a community docs jam I ran back in January: https://gitlab.com/saltstack/open/docs/salt-user-guide/-/issues/8
That example might be overkill, but it's just to show how the issue itself can guide someone through the process.
| ## Description | ||
| ### Doctype Name: {doctype} | ||
| ### Directory: https://github.com/thegooddocsproject/templates/{directory_name} | ||
| ### Sub-tasks |
There was a problem hiding this comment.
I'm using the Conventional Comments method to respond to your PR.
Question: Could you explain the "Doctype Name" and "Directory" fields to me so that I can understand them? As long as they make sense to you when you create the issue and would make sense to someone reading the issue when they reading it, these fields could be helpful. However, their purpose isn't immediately clear to me.
There was a problem hiding this comment.
So each of these issues is going to create template files for one specific "doc type"; that's a convention coming from Cameron's writing about the base template. I had some reservations about us coining this term since it could be confused with the "doctype" used in development when writing HTML, but I haven't come up with anything better. An example of a doc type in our system would be "API Reference" or "Tutorial". I debated whether this field was needed (might be obvious from the title of the issue). "Directory" is there so a newbie picking up one of these issues can go directly to where they need to be to start creating files, for example "https://github.com/thegooddocsproject/templates/tutorial". It's not that obvious I think for someone new to the project who isn't that familiar with our repo structure. And when we get to issues for nested doc types (like API Reference under Reference), the directory the files need to be created in won't be visible from the top-level of the templates repo.
There was a problem hiding this comment.
nitpick (non-blocking): We should be consistent is our spelling of "doctype/doc type/doc_type/doc-type/Doc Type/..." I've been using doctype, but only because I haven't got a better idea. I'm happy to switch if someone can suggest something better. My mild preference order would be:
- doctype
- doc-type
There was a problem hiding this comment.
Yeah the reason I've started to use "doc type" is to avoid confusion with the doctype declaration in HTML markup. Of the two that you recommended for preference then, my vote would be for "doc-type".
| {Optional: add any further explanation if the issue is not self-explanatory} | ||
|
|
||
| ## Helpful References | ||
| {Optional: Add links to anything that might help the templateer write this particular type of template. For example, a Medium article about how to write good tutorials.} |
There was a problem hiding this comment.
Suggestion (non-blocking): Perhaps use "Helpful Resources" instead.
There was a problem hiding this comment.
That sounds good. I'll make that change.
| Add an appropriate label to denote the relative priority of this template: | ||
|
|
||
| Label | Description | ||
| --|-- |
There was a problem hiding this comment.
Question: I'm not sure what this section does inside GitHub. Does it automatically assign these labels to the issue?
There was a problem hiding this comment.
No, it's just renders a little table, telling the creator of the issue which of our many labels they should assign specifically for priority. They would choose one and assign it using the normal label process. If you weren't familiar with our scale, you wouldn't know whether we ranked from 0-4 or 4-0, and what criteria you should use for choosing the priority.
| ## Description | ||
| ### Doctype Name: {doctype} | ||
| ### Directory: https://github.com/thegooddocsproject/templates/{directory_name} | ||
| ### Sub-tasks |
There was a problem hiding this comment.
nitpick (non-blocking): We should be consistent is our spelling of "doctype/doc type/doc_type/doc-type/Doc Type/..." I've been using doctype, but only because I haven't got a better idea. I'm happy to switch if someone can suggest something better. My mild preference order would be:
- doctype
- doc-type
Please review my proposed new issue template for a templateer to create a new doctype template.