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

Hello everyone!
So, I want to sort out all the content on the docs website, so that it’d make better sense, and help in taking further decisions wry docs website redesign as well as the content that requires updates:)

I found out an article that explains a bit about documentation and how everything can be classified into a-

  1. Tutorial
  2. How to guide
  3. Explanation
  4. Reference

I think these categories make sense for the docs website use case as well.

Here’s the article link: https://documentation.divio.com/

I’m trying to write everything down in this Google sheet. I’ll try to categorize as much as possible!

Sheet- Fedora Docs - Google Sheets

Please feel free to contribute, as I think a lot of folks here are the ones who wrote the articles and know best about them:)

To know more about what I’m working on, join this discussion thread- Redesign Docs front page layout- Outreachy Project 2022 (Help required) - #19 by likeanushkaa

2 Likes

How should we contribute? What level of detail are you looking to add to the sheet?

I’m all in. Are you aiming to design docs or all the docs?

2 Likes

Hi! So, as I mentioned in the sheet, I want to initially add the category of articles as one of the four mentioned above-

  1. Tutorial
  2. How to guide
  3. Explanation
  4. Reference

If you have a different categorization in mind, let me know. You can also mark where different articles have been repeated as before, which can be done by colour coding the rows.

It’s a bit of a tedious task as you have to read the article, mention it in the sheet and then mark a category. If there is a simpler way to do that, please let me know as well.

I thought I’d be able to add every article to the sheet, but I’m a bit under the weather last week- but I’ll finish this in the coming week!

Hi @x3mboy! So, I’m redesigning the docs website, but also want to provide an overall better architecture to the website- which would be possible when I know exactly what content goes where.

Plus, it’d also help us decide if some articles mentioned in the docs should be shifted to some other place, say the main website, etc.

Thanks for the excitement!:smiley:

If I walk through the current Fedora Server Edition documentation (everything beyond Fedora Server Documentation :: Fedora Docs), which I know reasonably well (because I wrote most of it myself), most of it falls into a mixture of how to and explanation. And if I have to decide between those, it is more or less a how-to style with some explanation added. There is only one tutorial so far (in the subsection named Tutorial) and no reference.

I’m not sure if this categorization is helpful in structuring and “librarianing” the extensive content. In Fedora, my first content filter wouldn’t be a tutorial or how-to, but the area in which my question or problem lies, so workstation or server, or overall network or the service (web server, DNS server, …). It is more of a semantic structure, less a methodological or typological one. A first level could be “Fedora release” with information about overview / what is new. Second level may be “Products” (Workstation, Server, …) and “general services” (Network connnection, quickdocs, Office apps, …). Or maybe quick docs is a third entry on level 2.

On the detail level, we need different types of documentation. And the differentiation into how-to, explanation, etc. could be a quality measurement and a way to optimize the docs.

But maybe I’m too conservative and too oriented to the known to be able to tame the beast of naturally grown content.

Hi!

After a discussion on this topic, It was decided to work on the content of Quick Doc as an example for analysis.

After going through quick docs, I just arranged the topics into a better sequence as well as marked topics that could be a part of some other group. See- Fedora Docs - Google Sheets

Also, while going through the docs, I found out that there are 5 different call-outs:
Note- blue
Tip- green
Important- red
Warning- yellow
Caution- purple

What exactly is the differentiator between these call-outs? Also I feel the colour coding is a bit off, say why should a warning be yellow and important be red ( red gives an impression of some error- it could be driving attention,but in the wrong way)

So I think we can form a system for these call-outs as well. Are there any ones I missed?

Please put thoughts around this!

Do you think adding such filters to the docs search bar would prove fruitful to the user?

Also, Is this something that’d be possible from engineering end at the moment?

Very interesting, such an overview about the article titles/topics and how they are assigned to the menu items! If you now categorize the items into one of the four types, I could imagine we will encounter some surprises.

Unfortunately, there is no style guide that could provide specifications for this. I’m afraid it all reflects subjective ideas of the authors or web designer rather than any substantive concept.

That would be great. It could be a first step to an urgendtly needed style guide rsp. writers guide.

This project enthralls me more and more.

1 Like

I think it could be useful as an optional filter and/or sorting criteria. Right now, we’re really happy to have a search function at all. It just benefits from further optimization and streamlining. I guess it would be not until a year from now that we could address that.

Hi all

I’am fairly new user to Fedora Discussion, sorry if my question may be out of place in this topic:

On what technology are based those three documentations frequently used in Fedora:

Are they based on open source projects that one can (re)use personnaly ?

Thanks

1 Like

Current Fedora documentation is based on asciidoctor adoc format using Antora to turn in the documents into a website. It’s an open source project (antora.org).

1 Like

These are pretty common admonitions in technical books that I’ve seen. That doesn’t need we need to use all of them. I agree that the default colors aren’t quite what I’d expect. That should be easy enough to change.

We should also have some standards for which admonitions we use when (and which we don’t use?)

So here’s my general understanding of how these are used (not necessarily how we’re using them in our docs)

  • Note: An interesting aside that is there as additional information, but you’re okay if you don’t read it
  • Tip: A suggestion that will make your life better in some way. Optional, but beneficial
  • Important: Additional information that you should know.
  • Warning: This will cause data loss, make everyone hate you, etc
  • Caution: If you follow the instructions carefully, everything is fine. But don’t step too far out of line or you’ll fall off the cliff.

As a first pass, I’d think we could sort all of our admonitions into note, tip, and warning. Important and caution seem superfluous.

1 Like

@bcotton - these colours and icon language can work IMO. I’ve added this on the figma file as well. What do you think about this?

I also found an article - Admonitions: Tips, hints, and Warnings. which explains when to use these admonitions, should fedora have such a guide of it’s own?

On it right now! You’d see some more additions in the same sheet today. Seems like a good idea!

Ok, I tried to work on this as well, you can see the comment above:)

Thanks for the motivation!! This helps:)

I like it!

That would be a good thing to include in a style guide. I added a note to the ticket.

2 Likes

Hi! Sure thank you for adding this to the ticket:)

Although now that I’ve done this, I’m stuck- what should I do next…any suggestions?

Let’s work with Fedora Design to get a color scheme and icons that feel uniquely “Fedora” and are coherent with the rest of our sites.

2 Likes

That’d be awesome!:smiley:

1 Like

File a ticket at Issues - design - Pagure.io

1 Like