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-
How to guide
I think these categories make sense for the docs website use case as well.
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:
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.
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.