Fedora docs design work

Greetings, docs people!

I’m a designer at Red Hat, and I’m part of the Workstation Working Group. I got interested in Fedora’s documentation a while back, and ended up spending some time looking at it from a design perspective. I thought that it was about time to share that work!

If you want to pursue any of these ideas, I’d be super enthustiastic about working with the docs team on them, but feel free to use this as you see fit.

The work I did had four parts:

  1. a review of Fedora’s existing documentation,

  2. a review of documentation sites belonging to other projects,

  3. a set of design goals,

  4. some tentative designs for updated docs sites.

The following is a quick summary of that work.

Fedora’s docs

Obviously there’s quite a range of documentation in Fedora. I found it insightful to analyse it according to a set of dimensions, including:

  • ownership - does a page belong to a particular team or edition, or does it fall into a more general project-wide pool?
  • length of time that the docs are relevant - is a page specific to an event, initiative, or release, or does it have more long-lasting relevance?
  • size and structure of each piece of documentation- is it single or multi-page?
  • intended audience - is the audience users, the entire Fedora community, or a sub-set of that community?

The interesting thing about these dimensions is that they all have implications for how the docs might be designed. For example, a site which caters to short-term, transient, internal pages, would be different from one that only deals with long-term user docs. As a result, and with so many types of docs, I think that it’s worth focusing on certain types.

Relevant art research

For this step, I looked at the docs of various other projects, including Ubuntu, Arch, Elementary OS, Rust, Kubernetes and Android. This allowed me to see common patterns, and identify lessons that can be learned. When judging how successful each project was with its docs, I looked at things like how active the docs were, the apparent quality of the content, and how easy the docs sites were to navigate.

I won’t go into everything that I learned through this process, but here are a few highlights:

  • Most projects include basic project information on their websites, and this tends to follow standard topics like how to install, how to get support, how to get involved, and how to find news about the project. This was interesting to me because this is documentation, and there is a division of labour that needs to established between a project’s main website and its docs pages.
  • User and contributor docs were generally separate. This seemed to help clarify the goal, scope and structure of each documentation site.
  • None of the other projects used the term “user documentation”. For example, Ubuntu calls it “Documentation” and “Desktop Guide”, and Elementary OS just calls it “getting started” and “install”.
  • Editing documentation in Markdown is the norm.
  • It often wasn’t clear what was being used for short-term, transient docs. In one case, I did see plain markdown files in a Github repo as a solution.

Design goals

There are a lot of requirements around Fedora docs, which I attempted to organise and prioritise as part of the design process. Two goals that I particularly prioritised were reader and contributor experience. We want people to read our docs, and that means that it’s important to design an experience where reading, searching, and browsing are all really rewarding.

Contributor experience can also be enhanced through design. How we frame the docs, how they’re structured, and the cues that we provide around contribution all play a factor.

A tentative design

Please be aware that the following designs are just a sketch - there are plenty of details left to fill in, and plenty of scope to make changes. For the mockups themselves, I’d suggest focusing on the main aspects of the designs, such as the content structure, the scope of each site, and the main interactions that each page affords, as opposed to details like the placement of individual elements, or the typography or choice of colours.

The big idea in these designs is that Fedora should have separate sites for internal project pages and external “user” documentation. There are a number of reasons why this separation is important, in my opinion:

  • Internal project pages follow more of a pre-established structure, whereas user documentation is more organic in nature (the structure is messier and coverage is more uneven).
  • Internal project pages are generally owned by individual teams, whereas user docs have shared ownership (possibly with management by a dedicated team).
  • From a reader perspective, user and community content are separate domains, with different expectations. Mixing internal and external docs is potentially disorientating for visitors, and makes it hard to design sites which have a clear focus and messaging.

So what might these two sites look like?

Site 1: “Fedora Pages”

“Fedora Pages” is a working title for a site containing internal project documentation. The site is structured as a single tree, with individual teams having ownership of their own pages. The home page leads with a clear statement of what the site is, what content it has, and what people can expect from it.

Fedora Pages home page:

The quick links on the home page are a way of linking to popular pages and to areas where there is activity that people can participate in. The menus at the top of the page also provides quick access to commonly used resources.

Fedora Pages example content page:

A path bar allows navigation up and down the site docs tree. Pages includes cues which emphasise the collaborative nature of the docs, including a time stamp, a copyleft licence, a link to a contribution guide, and an edit button.

Site 2: “Fedora Documentation”

“Fedora Documentation” is the second docs site in the design, and is intended to contain user documentation. It includes two types of content: single page articles, and multi-page guides. The bulk of the site’s content would be articles, which would be organised by tag. Guides would be a small collection of content based on the existing guides, such as the installation guide and the edition guides.

The articles content could possibly be based on the existing quick docs.

Fedora Documentation home page:

Fedora Documentation example content page:

A major goal for the documentation site is to encourage the growth of the user docs and the docs contributor community. The site’s free organisation structure is key to this, by allowing people to easily add their content without the need to fit into a pre-established structure, and by allowing contributor groups to organically form around content that they’re interested in.

Another important way in which the design aims to catalyse contributor growth is by featuring recently updated and popular content on the home page. Not only is this a great way to make the site engaging and helpful to readers, but it also allows contributors to collaborate on the relevant material of the day.

Concluding thoughts…

There’s a lot more that could be said about this work, and I have more material that I can share with those who are interested. However, this post hopefully covers the main points and gives people something useful to think about.

The main docs areas that aren’t covered here are the developer docs, as well as short-term working pages. I have ideas and opinions about these, but not as much in terms of design work.

Presenting design work in this way is really Not The Way It’s Supposed To Be Done, and I apologise for not working more closely with the docs team on this. My sense is that the Fedora Pages site could be realistically implemented using existing Antora infrastructure. Whether that is true for the Fedora Documentation site is less clear…


You are surely most welcome! We have already discussed several times that our docs design needs a refresh.

I’ll make some initial comments on your ideas.

This breakdown is already the current situation. It is not disputed and, to my knowledge, no one wants to change it. Therefore, on the docs page, the upper part is the “user documentation” and the lower part is the “project documentation”. And hence the term "user documentation.

Hm, we are just trying hard to make the (user) documentation less “messier”. And the project documentation pages follow a kind of typical content topics, as well as the user documentation pages, although the typical content differs, of course.

No, the vast majority of pages are owned by a team, project documentation as well as user documentation. See Fedora docs is about to change significantly! Check it out still in statu nascendi. – Fedora Community Blog There are some exceptions. E.g. Quickdocs is “owned” and cared about by the docs team, and some general guides as Anaconda doc or dnf doc. The team that owns a documentation item is responsible for creating, updating, everything in terms of asciidoc article. The docs team provides support and is organizing the transformation into a website.

As of site 1 (Fedora project documentation) and site 2 ( Fedora user documentation): Both share the landing page. The con is, the page may make an overloaded impression while having quite different addressees. The Pro is, it makes it clear, nothing falls from the sky, but everything must be created and maintained by real teams. Contributions are vital.

Regarding Project Pages: I’m not sure if we will give up the current systematic approach and turn it into a kind of “loose-leaf collection” collection.
In case of user documentation, I’m quite sure we don’t want to do that. We are not a news site, “recently updated” is not a relevant criterion. I don’t want to read a “software raid” article, because it is recently updated, if I have to deal with a network issue. Same is true for “most popular”. And I also think categorizing by “systemd, command line” etc. is not helpful. So, these items should not occupy the central part of the page, I think.

Instead, we need other information: date of last relevant content update, Fedora release(s) the article is tested against, name(s) of author(s), name(s) of other participants (reviewer, translator, etc.). The way we do that on server docs (e.g. Fedora Server Installation Guide :: Fedora Docs) is very rough in terms of design, but currently we haven’t anything better.

The goal is agreed, but the way should be different. We have a pull request workflow, we have reviewer, we have a concept regarding the content, we want to have QA. So we have a pre-established structure, and that is essential. But we must establish an as low barrier as possible, must establish an onboarding process, etc.

Well, that are some thoughts of mine. I look forward to an exciting discussion!

1 Like

This is very good, I think your contribution will be interesting to @duffy work. I’ve been pointing out certain things, like privacy and data protection calls on the new website homepage, but folks have had other really cool ideas like the sustainability and ecology project.

So welcome

Yeh! lack a link to my calls for privacy issues, please |o|

Hey Alan! Can you share more details about the research you’ve done? I am trying to create an IA of the docs website myself, and this would be helpful!

On this, I was thinking about introducing a sort of template with the Fedora Docs style guide. Something that Medium does, if you would have seen that.

I think I don’t agree with you on this point because-

  1. I feel all the information related to Fedora should be collectively available together. Think of it as a one-stop destination for users and contributors.
  2. I feel that with good differentiation, we could definitely distinguish between user and contributor docs. Although with the Fedora wiki as well, we need to define how we want people to perceive the docs website.
  1. On the contrary, I think contributors could understand where a piece of information is missing in the project and user documentation and suggest improvements in both?

I like the use of categories in the articles, but I would also like to understand what kind of categories have you thought about, and what are they generally based on?

Looking forward to hearing back from you!


Thanks for the detailed reply, @pboy !

You’re quite right - the split between project and user documentation already exists. What my design does is take it further, with different:

  1. domains
  2. home pages
  3. site structures (project docs would be a tree, user docs would be flat and use tags)
  4. page structures (user docs would be generally restricted to a single page per unit)
  5. management and editorial processes (project docs is a set of team pages, where each team manages its own pages; user docs would be edited by a central team)

I think we’re mostly on the same page here. The user docs that i envisage are essentially an expanded quick docs, with a small number of guides bolted on the side. Those quick docs would be managed by the docs team as they are now.

My point was that those quick docs are like a big umbrella, with oversight from a central team. That’s a bit different from, say, FESCo’s docs, which are like a separate little kingdom.

The exact type of content we surface on the front page definitely needs more discussion.

There are two main things I was trying to do with this part of the design. First, I was highlighting that the docs are a living, active thing - I think that makes them more engaging, particularly to potential contributors. If there’s no sign of life, you’re likely not to be as motivated to participate!

The second goal was to reflect changing interests amongst users, as well as flagging particularly useful content.

I think that those goals are worthwhile, but they could be achieved in a variety of ways.

The particular tags in that example might not have been the best. The point of using tags is to allow user navigation and browsing, without relying on a fixed content tree. For example, if someone has a networking problem, it would be good for them to be able to view all the docs we have on networking.

The problem with trees - and the reason i steered clear of them for this part of the design - is that they become difficult to manage the more content you have to accommodate, plus they obviously don’t handle overlapping topics. The objective here is to facilitate growth. We’re not making a book - we’re making a library.

Absolutely! So far it’s all notes in a Google Doc. I’d be happy to clean it up and share it, but i’m not sure what the best way to do that would be…

I’d be interested to see what you come up with here, but let’s say I’m sceptical! I just don’t know how you design a home page which is a really awesome gateway to two distinct sets of content.

I also think that there’s a real risk of confusing users about what the purpose and role of the site is. That’s something that people often decide on within a split second of arrival. There’s no room for mixed messaging.

The categories in the mockups are essentially placeholders - the exact terms to use require a lot more thought!

It is a conceptual issue, not a design issue, whether we want to start with user doc and project doc from the same page or not. There are reasons for both variants, and the solution is ultimately the result of weighing and evaluating different conceptual criteria.

To my knowledge, there is no other distribution that appears as pale, frayed and indistinct as Fedora. At present – and that means 3-5 years rather than months – we, as Fedora, should beware of fray even further and pull the two areas apart. We do not have a central entry page from which to access all Fedora domains. Everything is largely fragmented. The base address fedoraproject.org is for years a redirect to a download page (and some of us are really wondering about a lack of contributors). The only site that offers a substitute to some extent is the docs page – without any change foreseeable. We started a “Fedora Website revamp” group about a year ago. And what are they doing? They are tinkering with a Fedora Workstation download page for a year now (a gross overstatement, not to be taken literally). Of course, it is undoubtedly important work. On the other hand, we have still no concept about a “Fedora website”. And it blocks more or less and certainly unintentionally progress in other areas.

From this concludes for the docs page, we need an interim solution that preserves the current content and structuring and transfers it to a better design than the tile structure. And if we are good and successful with it, we might be able to provide an idea of what a central portal page might look like and how it can spread out into the distinct sectors.

I can’t see that. User documentation is also organized as a tree. The docs page is subdivided into the areas of the individual editions, which in turn are subdivided into further areas such as installation, administration, etc., and subareas.

This is incorrect. Even with user documentation, there are usually several subpages for each non-trivial unit. See, for example, Installation in the Server documentation or the equivalent “Provisioning Machines” in CoreOS.

That’s incorrect as well. You may have a look at the new intended structure of the docs page . The vast majority and nearly all the most important documentation is managed by teams other than docs team. The work of the docs team is mainly to create the appropriate framework, to produce the web pages from the team documentations and curating.

This is probably true in the future, but maybe not. Quick Docs is currently a mess. It is partly a way out of the previous situation that documentation like “Installation Guide” and “Administrator’s Guide” are largely obsolete and useless, but monolithic and hard to update. Both will no longer exist in this form in the future. Corresponding articles in Quick Docs could be transferred to other places.

Most of the other parts are irrelevant or even misleading and dangerous for 80% of Fedora distributable (e.g. virtualization for servers). They are essentially additions for a workstation documentation, but that unfortunately does not exist.

What solution we will find for Quick Docs is currently open. In any case, it will not be the “main work” of the docs team. Among other things, it was discussed whether to ask.fedora-team could take over Quick Docs.

That is likely. But it is only a small part of Fedora docs! Therefore, the design should not focus on it. This is an albeit important “side job”.

Very much agree to that idea. Question is, whether docs are developing too slow for that purpose. I’m not sure about it.

Agreed to that concept, too.

This is a valid argument and should be resolved.

I see our discussion is decidedly productive and interesting!

I totally agree about the fragmentation issue, but I also think that it’s important to have the right combination of solutions. Simply combining all the content we have doesn’t naturally translate into a great user experience.

For me, project docs and user docs are crucial and fundamental, but also different. If we can create great platforms for those two, then consolidation can follow. (Personally, I would be in favour of retiring the wiki and the developer sites, as part of that consolidation.)

But also, as you’ve pointed out, the main website has a critical role to play in this. I would like to see some of the basic project documentation move from the docs to that site.

Sure. That’s where the guides part of my proposal fits in. Perhaps it would be clearer if I were to draw the content structure out, so you can see how the pieces would fit together…