Making Fedora Magazine Accessible: Why Technical Documentation Needs Beginner-Friendly Writing

Site Help & Feedback
1

Fedora’s articles need improvement in terms of accessibility and clarity for complete beginners. For example, consider this excerpt from the introduction of this article The pieces of Fedora Silverblue:

And you can get more answers by looking at how libostree works. libostree treats the whole tree like it’s an object…

It is entirely unclear what is meant by tree to any ordinary reader. In well-written scientific papers, authors begin with an introduction that establishes and defines key jargon and fundamental concepts to readers, before diving into “complex” topics (the old adage applies here: a competent person should be able to explain a “complex” topic to a 5 year old).

There’s a growing emphasis in academic publishing that good scientific writing should be accessible to non-specialist audiences. Fedora Magazine articles should adopt this same principle of progressive disclosure—starting with basics and building toward complexity.

To be clear, this is not a criticism of any individual author (in fact this article is rare in its noble attempt to explain and contextualise an entire OS to readers, and it does so successfully!). Rather, it highlights a systemic pattern across the site (and the industry!) that needs addressing. In my eyes, the solution lies in implementing editorial guidelines, writing templates and checklists that remind contributors to:

  • Assume minimal prior knowledge from readers
  • Define technical terms when first introduced
  • Build concepts progressively from simple to complex
  • Include a “prerequisites” or “background knowledge” section when necessary

FOSS (Free and Open Source Software) is a core ideology that Fedora champions and this philosophy extends beyond code—it encompasses knowledge sharing including infrastructure, hardware and product design decisions (aka transparency). If we truly believe in the principles of openness and accessibility our documentation must reflect those values. Knowledge that’s technically “open” but practically inaccessible due to poor communication defeats the purpose of FOSS ideals.

Transparent, beginner-friendly documentation isn’t just good practice—it’s an ethical imperative that aligns with Fedora’s stated mission. By lowering barriers to entry through clearer writing, we expand the community, empower more users and strengthen the entire FOSS ecosystem. Do not confuse beginner-friendly documentation with conceptually simple documentation, these are not mutually exclusive things as is highlighted before (“Build concepts progressively from simple to complex”).

2 Likes
2

I think that you first need to define the target audience and build the article around that. The article you quoted will never be accessible to a beginner. It clearly isn’t intended to be. It is filled with advanced concepts. Making that article beginner friendly while covering all the topics it covers would turn it into a literal book. That article assumes a lot of prerequisite knowledge. The fact that “tree” isn’t defined is the least of the problems a beginner would have at tackling that one.

You could, of course, create an article on a the same general topic that was more appropriate for a beginner. Realistically, you wouldn’t need to talk about libostree at all. Understanding the underlying system to that level of detail is in no way needed in an introduction to the Atomic distros. But that isn’t what that particular article is.

Realistically, I think you need to have both articles targeted at an advanced audience and those accessible to beginners. And, importantly, clearly differentiate which is which because we don’t want articles on advanced topics to start with 5 pages of definitions. An article on btrfs internals can’t possibly define and impart the knowledge to understand all the terms that would be used in it and still be considered an article. But there is no way a beginner would understand such an article in the first place.

4 Likes
3

In the scenario we are referring to, I do not think you’d have to write a whole book, you could link to Wikipedia articles worst case or just be concise. However, if it is required that one take an free computer science course this should be explicitly stated.

Realistically, I think you need to have both articles targeted at an advanced audience and those accessible to beginners.

I mean that’s also a solution to have separate articles, the only downside is that you have to focus on integrating them by doing the aforementioned checklist, if you were to make them into a series, which requires more foresight by the author. Unless… the author writes it initially in one larger document and then segments it after, in that case we might be onto something here. Yet the overall message of post still applies and I do not want valid and important side-critiques muddying that.

You could, of course, create an article on a the same general topic that was more appropriate for a beginner. Realistically, you wouldn’t need to talk about libostree at all. Understanding the underlying system to that level of detail is in no way needed in an introduction to the Atomic distros. But that isn’t what that particular article is.

That’s also another absolutely valid way to go about it, but on its own I do not think it’s as systematic, effective and efficient without combining it with the aforementioned way. Could lead to a lot of overlapping redundant articles, especially if written by different authors not communicating with one another. However, to address this:

However, if it is required that one take an free computer science course this should be explicitly stated.

Maybe there could be two pages one dedicated to people willing to learn from beginner to expert, and one for users just wanting to use their dang computer!

So I think your criticism is absolutely valid, maybe there needs to be an educational page full of article series or “books”, another dedicated to practical user guides for beginners and another for advanced articles for experts. In either case, to make the process more efficient the later two could be directly derived from the segmented “books”.

But there is no way a beginner would understand such an article in the first place.

Now I think you are being a bit absolutist here, and perhaps defeatist. I think beginners like me can absolutely understand things like this article given a proper structured preliminary introduction as I argue in the first place. Some articles especially scientific articles are much longer than your average Fedora Magazine post, and are by no means considered books.

4

Hello @sprout3425 and welcome to :fedora: !

The article is about 5.5 years old, some links are no longer valid, and the concepts described will most likely be changed in the next few releases of Fedora.

Fedora Magazine is not a Fedora Documentation and I don’t know why the author of the article doesn’t even mention the official User Guide. If you’re interested, you can find it here:

1 Like
5

The document does start by calling back to its predecessor:

Fedora Silverblue provides a useful workstation build on an immutable operating system. In “What is Silverblue?“, you learned about the benefits that an immutable OS provides. But what pieces go into making it? This article examines some of the technology that powers Silverblue.

…which steers the reader towards reading that previous article if they haven’t already. That article is relatively more introductory, though still not really targeted at a beginner.

In practice there’s always going to be a “ladder” of sources with progressively increasing complexity. I also enjoy reading scientific articles outside my formal training, but they still have some implicit prerequisites. For example, an article about virology that’s accessible to the interested layperson is nevertheless not going to define what a virus is from first principles. Likewise, “beginner” is relative and contextual. Do we target articles at someone who has literally never used a computer before? (I don’t mean that entirely facetiously - it’s indeed what home computer manual authors in the 1980s had to do.) I think practically we don’t - we orient to a userbase where virtually everyone has at least some level of everyday computing experience.

I certainly think there’s plenty of room for improvement in Fedora documentation, and that’s a current focus area for me and others. “Is this article appropriately pitched for its audience?” is a question I’m asking whenever I review a document at the moment.

The Fedora Magazine team is also very open to new writers and editors.

I very much agree with these ideals.

6

Not that it matters but I have a degree in biology, and I can tell you that this is very much dependent on the article, project, authors, and their goals and target audience.

Exactly, and unfortunately I do not think these articles are well orientated to introducing “Linux” to everyday computer users, because at the end of the day that’s the goal.

Sure, but I absolutely can not see why adding these checklists/guidelines to the templates of writers and editors should not occur.

To be honest, I would say the Fedora Magazine articles almost do a better job at contextualising and familiarising users with the OS, compared to the docs.

I commend everyone for their openness to discuss, to clarify I am not here to bash people, but at the same time I want to make my feedback very clear as I feel like it should be an area of improvement.

7

I appreciate your clear articulation of it. I’d say that I don’t feel any of us are blind to the current state of the documentation, and there’s an awful lot of work for us to do.

1 Like
8

I’m a somewhat confused here. If I understand correctly, in your first post you stated that the article as a whole was too complicated for a beginner, and now you claim that it is better than the official documentation for Fedora Atomic Desktops.

9

This is the key question though. Is that the goal? Does Fedora Magazine exist solely to introduce Fedora to every day computer users? If so, that would certainly set the expectation that all the articles should be directed towards that audience.

However, I am not sure that actually is the primary goal.

10

What does the Magazine publish?

The content of the magazine varies, but mostly includes:

  • General Announcements / News
  • Tips on how to use software in Fedora
  • Ideas for cool apps to try
  • Ways to more effectively develop software using Fedora
  • DIY hardware projects you can power with Fedora
  • …​ And everything else related to Fedora in general!

Source: Fedora Magazine | Docs

It is not meant to replace anything it is an addition to everything. For the Fedora Community driven by volunteers of the Community. Feel free to join :wink:

11

I’ve been reading this thread and there are some good things brought in, but I struggle with this question:
Does Fedora Magazine have to have complicated articles in which (new) things are explained in-depth, or is it better to put those in Fedora Docs? In the magazine you can then create a lightweight story about the same subject with a link to the long (and much more technical) story. So if people want to read it they can, if not then the lightweight version is either enough or the subject is not interesting for them.
I hope the word Magazine in English means the same as Magazine in Dutch where it is something you pick up and read when you are at the hairdresser waiting for your turn. Not a place to put difficult technical articles in.

In the in-depth article, why not begin with explanations of the “basic” things the reader should know before being able to understand the article. When you know it all already (senior Fedorian) you can just skip that part and start reading the article, if not read the explanations first.

4 Likes
12

Thanks for adding this, the orientating the reader with fundamental concepts and jargon part is literally a no-brainer, and I wanted to make this very clear and prevent people from just blindly denying or muddying the idea with tangential concerns.

13

Ok sorry you are right, let me rephrase this, it should at the very least be a goal, if not the primary goal for all of the reasons listed in the initial post.

14

It really, really, isn’t a no-brainer. You are deeply underestimating how hard this would be for advanced technical content. It would end up reading more like a research paper than an article. You would need pages and pages of definitions and explanations.

Why? Because every time I try to explain one word, I would then need to explain all the things that required to explain that. There are different levels of material and the more complicated material needs to assume a base level of knowledge.

IMO, it is all about the target audience. If I am writing an article intended for a developer, I shouldn’t need to introduce an explain all the common words that would be in that article.

For example, if I am writing an article about how to use a toolbox to do C++ development in Fedora, I shouldn’t have to explain what a compiler is, how to structure the source files or what cmake is. That is assumed prerequisite knowledge. i.e. If you don’t already know how to write, build and deploy C++ code, you shouldn’t expect that an article about how to use a toolbox to enable that process will be understandable to you.

I should, however, be clear in introducing the concepts surrounding toolbox which is the focus of the article.

2 Likes
15

I think there is some level of intuitive ‘unspoken’ sense involved. For example, clearly it would not be expected that a writer goes down a cycle that leads them to explaining the etymology of each word, and the philosophy and science of language (although that would be cool if they decided to!).

Maybe I am being insensitive and communicative competence is not as easy for everyone to achieve, but even in that case, that’s what the implementation of guidelines is for, and people ought to learn to communicate more competently. One simple and easy way to ensure communication is more clear is to assume your reader knows nothing (it really does not cost as much as people insinuate, merely a time investment with disproportionate return). If you do this, and then derive other articles from one larger comprehensive article, in the long run you make much higher quality series, expand the community and save time doing patchwork and teaching people things your article failed to do.

This response has probably occurred because some of my responses may have come out as jabby, but I assure you it’s not my real intention.

Even if this were the case, this has been addressed by the article fragmentation into a series idea, but yeah the downside with this idea is that it’s a time investment, which I think is well worth it.

Actually now that I read the later half of what you have said, I do see where you are coming from.

Yes, I agree in that specific context you provide, but not all topics are that narrow. In that example it’s obvious that the reader should know a little bit about the programming language C++ and want to learn to do the things the article describes. However, in an example such as “What is Silverblue?”, I think we both agree that at the very least prerequisites or highlighted words with appropriate sources should be included.

I agree and the title and arguably introduction of the article should make this clear, in an article like “how to use Toolbox to do…”, the article should briefly introduce Toolbox and cite sources that help it explain what Toolbox is, ideally within the proper context. In addition, it could refer beginners to a general article introducing Toolbox, before pointing even less familiar readers to an article explaining what Silverblue is. I guess my problem is that a lot of articles do not include titles and/or introductions that contextualise an article to people of different skill levels, and I feel like it’s not a huge ask.

I think we are in agreement and thanks for providing some nuance to the discussion. I definitely revoke my no-brainer (I was not thinking/anticipating) “no-brainer” statement as there are clearly nuanced perspectives on the matter.

16

Agree with sprout. Although not only “complete beginners” have trouble with that article, and I believe I read it myself a few years ago to find out what Silverblue was and left early without a good answer.

I’m not a beginner, have been using Linux since Slackware came on floppies, and took CS as well. I know what immutable means. But as soon as the person starts talking about libostree I have no idea WTF that is any longer. I looked at its docs of course, but it was filled with similar recursive references and no graphics (am a visual thinker).

Further, we have a nice mechanism for progressive disclosure, the details and summary elements in HTML. The expert passes over them, the beginner clicks for details. Of course the content still needs to be written. Perhaps an include link to a glossary as cache to reduce the drudgery over time?

17

I forgot to provide an example of what I am suggesting: Working with Btrfs – General Concepts - Fedora Magazine. I feel as if this series does a better job compared to the average article on the magazine.

18

As a general reply to the concerns raised here: we value those comments and we welcome contributions. If you find parts of the documentation that you think should be better explained, please file an issue or open a PR.

The Fedora Magazine relies on contributors to write articles so there is only so much guidance / editing possible. The best way to make articles accessible is to contribute accessible articles or monitor article submissions and review them.

3 Likes
19

This criticism is very broad and is especially applicable to documentation, which I had a discussion with another Fedora team member about. Please read the entire post, there is a much more efficient solution compared to filing some issues on a per article basis. I appreciate the work you all do.

20

Could you please provide a link to this discussion?