You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I find the contents of the existing how-to and tutorial doc templates confusing.
They contain both template and instructional text, without a clear distinction between the two. Some useful template elements seem to be missing, such as prerequisites and procedure sections. I'd like to separate the instructional text from the template text by moving the instructional to a separate document.
Implementation ideas
No response
The text was updated successfully, but these errors were encountered:
As a developer, I don't find this confusing. Instructional text is minimal, reminds me of what I need to do, and then gets out of my way.
History suggests that folks just want to get the job done.
They will go looking when they have specific questions, otherwise, minimal guidance in-line is best.
The TODO comments are clear: do what is in this comment block (as appropriate) and then delete it. It's a reminder that includes the text you need that is inconvenient to remember.
At the moment, prerequisites are only present in the tutorial document (as that is the only place that clearly requires it). We could add it to the How-to template as well.
It should be clear that a how-to is not necessarily a single "procedure" (and we avoid the word procedure universally as overly formal).
If you want to add additional notes related to creating docs of various types, the existing docs how-to is probably the right place to do it.
Description
I find the contents of the existing how-to and tutorial doc templates confusing.
They contain both template and instructional text, without a clear distinction between the two. Some useful template elements seem to be missing, such as prerequisites and procedure sections. I'd like to separate the instructional text from the template text by moving the instructional to a separate document.
Implementation ideas
No response
The text was updated successfully, but these errors were encountered: