Docs: There is no clear differentiation between Tutorials and How-To Guides

[trgeiger]

We currently have 2 main categories for our docs named "Tutorials" and "How-To Guides." These are basically synonyms unless differentiated in some way in our documentation.

These should probably either be combined into one category, or else the existing documentation in each category should be re-categorized and one of the 2 categories should be re-named according to some new difference in purpose between the 2.

[rashmi43]

I can take this up once we know which how we want to update it

[joelanford]

My interpretation (I might be wrong) is:

• Tutorials are for broad, primary use cases
• How-To Guides are for more niche use cases

Regardless, I do agree that the distinction is not obvious and we should probably try to clarify.

Honestly, I think a primary reason to clarify is so that contributors to the docs have a clear mental model for where to add the next thing.

[trgeiger]

Yes, exactly. The way I was thinking about it, I imagine the difference between the two would largely come down to formal differences, which if clarified would help document writers with the style and tone of new contributions. I imagine Tutorials being detailed and thorough walkthroughs of more involved use cases, whereas How-To Guides could be more truncated reference material for shorter, more common commands? But that's sort of opposite of what you describe above as your intuition, so the terminology for the 2 categories probably does need tweaking--even just being much more descriptive with the intent of each category, like "Common Use Cases" and "Uncommon Use Cases" or something. "Long-form Tutorials" and "Common Commands." Definitely worth getting team input.

[github-actions]

Issues go stale after 90 days of inactivity. If there is no further activity, the issue will be closed in another 30 days.

[github-actions]

This issue has been closed due to inactivity.