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:
a review of Fedora’s existing documentation,
a review of documentation sites belonging to other projects,
a set of design goals,
some tentative designs for updated docs sites.
The following is a quick summary of that work.
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.
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.
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.
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?
“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.
“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.
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…