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-
Tutorial
How to guide
Explanation
Reference
I think these categories make sense for the docs website use case as well.
Hi! So, as I mentioned in the sheet, I want to initially add the category of articles as one of the four mentioned above-
Tutorial
How to guide
Explanation
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.
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.
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?
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.
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.
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).
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.
@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?
