Classification of all the content on the docs website (Contribute if you can!)

A “tutorial” vs a “how to guide” seem the same to me - I looked in the spreadsheet to try to get a sense but I didn’t see any examples of tutorials. Do you have any ideas what criteria might categorize a document to be a tutorial vs a how to guide, or any thinking about what the difference between those two might be?

1 Like

FWIW I just went through a number of the docs for RHEL and it appears only note and important are used there.

1 Like

The difference is gradual in terms of scope. A tutorial usually refers to more complex and larger contexts and includes contexts. A how-to refers to more narrowly defined topics.
Example: A tutorial about planning and setting up a mail service from postfix, dovecot, etc. incl. DCIM and configuration of the DNS entry of the domain. A how-to about configuration of Postfix virtual domain mailboxes.

I could come up with any number of things. I just don’t know what we have to consider in the intern program. And what are the next steps that we need to do under the program.
@bcotton. Do you know, or what is the plan? (sorry, I just don’t know about the program, but would be eager to start to work with Anushka and her ideas and plans)

https://pagure.io/design/issue/816#comment-794302

Here’s my suggestions.

Thanks, is this a Fedora-specific definition or a general / tech communication one?

I think the https://documentation.divio.com site (from @likeanushkaa first’s post in this topic) actually covers this well. It includes what Peter says but I think makes a distinction a little stronger, even. That is:

Tutorials:

In specific, from https://documentation.divio.com/how-to-guides/:

How-to guides are wholly distinct from tutorials and must not be confused with them:

  • A tutorial is what you decide a beginner needs to know.
  • A how-to guide is an answer to a question that only a user with some experience could even formulate.

In a how-to guide, you can assume some knowledge and understanding. You can assume that the user already knows how to do basic things and use basic tools.

Unlike tutorials, how-to guides in software documentation tend to be done fairly well. They’re also fun and easy to write.

It also makes this distinction: tutorials are “learning-oriented”, while how-tos are “goal-oriented”. It gives these analogies:

For tutorials:

What you teach the child to cook isn’t really important. What’s important is that the child finds it enjoyable, and gains confidence, and wants to do it again.

For how-tos:

A recipe has a clear, defined end. It addresses a specific question. It shows someone - who can be assumed to have some basic knowledge already - how to achieve something.

Someone who has never cooked before can’t be expected to follow a recipe with success, so a recipe is not a substitute for a cooking lesson. At the same time, someone who reads a recipe would be irritated to find that it tries to teach basics that they know already, or contains irrelevant discussion of the ingredients.

I’m not sure that this particular four-category classification system (“The Grand Unified Theory of Documentation” ) is really the ultimate_ one — there are other ways to slice it. But it’s very well thought through and every well explained — I’m impressed.

1 Like

I just worry this is documentation-specific jargon that is going to be lost on users who just want to find help in figuring something out :-/

1 Like

That’s a reasonable concern — there’s a difference between using the Grand Unification Theory for our own understanding and conceptual structure vs using it to present things to users.

That’s what I meant with “context”, but it is not just for beginners. I’m working on 2 tutorials for Server docs, setting up a mail service and installing Server on a remote rented hardware. They are definitely not for beginners. But they are no how-tos because you need a lot of explanation, aka learning, to be able to make decisions, another element of tutorials.

It’s nothing for the users, indeed. As I discussed with Anushka Jain, we would use it as a tool to sort the existing articles and to put them into a more systematic structure. And hopefully reestablish the original goal of Quick Doc. At least, I would be glad if we could this get running within the intern program (or without, or what else. Currently, I don’t know the details).

I like the way the coloring is ordered from least important to most important along the color spectrum (blue to green to red). I find that visually intuitive somehow.

2 Likes

An update on the admonitions. So, previously decided going with tips, notes and warnings. @duffy helped me with the fedora design guidelines on this.

But then after seeing Red Hat’s style guide, we replaced tips with important.

The visual design of the warning with a border around it is the one we’re thinking of going with.

I’d like to have a poll on whether we should have tips or important or just notes and warnings- i.e. Two admonitions instead of three.
( Had this thought because we have a repetitive blue colour and no other fedora colour is mild/ neutral enough to become a part of this style guide- can see in image where I tried the green shade for tips)



1 Like

Discourse has a poll feature. My 2¢, as I stated earlier, is that I like having three levels of importance with the “subtlest” color – blue – used for “notes” that can be glanced over and the “loudest” color – red – for the warnings. It also makes sense to me that the intermediate level (“important” or “tips”) should be colored midway along that color spectrum (i.e. something in a greenish tent). I could go either way with “important” or “tips”. I guess I’d lean towards “important”.

  • notes, tips and warning
  • notes, important and warning
  • notes and warning
0 voters

Please vote!

Hi everyone. I have tried to categorize the different sections of the Fedora Docs website in another way-

The idea is to put all kinds of “installation guides” together. This could have a “release history” for old installation guides.

The other idea was to introduce a “version history” where we have the release notes of the current version but only the changelog (Distribution wide changes, Common Bugs, Revision History) of the older versions. Let me know your thoughts.

Please go through the other sections as well. I still have a section called “Getting started”, which is taken from Quick Docs, and I couldn’t figure out where to put these miscellaneous items.

If you have ideas, please share!

1 Like