Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the How-to and Tutorial templates #33276

Closed
rolfedh opened this issue May 10, 2023 · 3 comments · Fixed by #33420
Closed

Improve the How-to and Tutorial templates #33276

rolfedh opened this issue May 10, 2023 · 3 comments · Fixed by #33420
Labels
Milestone

Comments

@rolfedh
Copy link
Contributor

rolfedh commented May 10, 2023

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

@quarkus-bot
Copy link

quarkus-bot bot commented May 11, 2023

/cc @MichalMaler (documentation), @ebullient (documentation), @hmanwani-rh (documentation), @inoxx03 (documentation), @michelle-purcell (documentation), @sheilamjones (documentation), @sunayna15 (documentation)

@ebullient
Copy link
Member

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.

@rolfedh
Copy link
Contributor Author

rolfedh commented May 16, 2023

Thanks again, @ebullient. I added the prereqs and a couple of lines based on our conversations. I welcome your feedback on the proposed changes.

@quarkus-bot quarkus-bot bot added this to the 3.1 - main milestone May 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants