Proposal of an umbrella plan for content

Before we discuss individual content, we should develop a longer-term concept. Here are a few introductory theses.

  1. Looking through our existing documentation, the shortcoming is not so much in the individual texts, but primarily in their structuring and arrangement. The structure pretends there is a unified Fedora, organized by releases.
    But in fact, Fedora is primarily structured by editions, even if they are built on a common base.

  2. The shortcoming is clearly evident in the Installation Guide and Administrator’s Guide. The editions differ in such a way that neither an overarching Installation Guide nor such an Administrator’s Guide is possible.

  3. The two aforementioned guides are very comprehensive and monolithic. Such a structure is difficult and time-consuming to maintain, for texts the same way as it is for program code.
    And then there are also contradictions to editions, presented on the same page, which also describe e.g. an installation, but mostly without reference to the “Installation Guide” and also in at least partly completely different flow.

  4. Apart from the structure, very many articles or parts of articles are well suited and meaningful. Some need to be updated, but very rarely discarded completely. However, there are a lot of gaps that are waiting to be filled.

  5. A plan to proceed should take into account:
    (a) a structure and presentation to match the current structure of the Fedora project
    (b) (re)use as much of the existing text body as possible to keep the workload within limits
    (c) break down the changes into small enough steps to allow rapid publication of changes and avoid long “latency” periods

  6. A possible result could look like this
    (a) Abandon structuring by releases, instead have a single “Fedora” box with an overview and reference of where to find what, including release notes for current releases. Abandonment of a central installation and Administrator’s Guide.
    (b) Most editions already have documentation on installation and administration and can take over this function. As far as I know, Workstation and Cloud are missing. Workstation would be easy and quick to create from existing text, if Workstation WG has nothing. Cloud would just be missing, but is now also missing completely.
    (c) One or more new box(es) with ‘Reference Guides’ extracted from the current guides as appropriate.
    = Fedora Tools Reference (Anaconda, DNF, System Monitoring, Kernel Configuration, Display Server)
    = System Services References (SSH, Web Server, etc)
    = maybe some additional guides

5 Likes

I think there is a limit of what people can physically edit, and that limit is hard to lift without additional tooling. For example, a single page may have tree levels of depth to switch interactively - from beginner (run commands) to advanced (what is going on) and to details (how it works). Editing such page would require the ability to see all there levels at once. Maybe with some advanced diff engine with transparency and animated transitions. But the complexity is not only in the depth of content, it is also in the granularity - splitting the content into blocks and detecting how blocks are linked to know if editing block will break something or not. This way the same block can be reused between different “Editions”. That in turn requires a tool capable to visualize the content as blocks and links, or in other word - representing text as a graph. There are some existing solution that deal with text as a graph. MediaWiki or AppFlowy are the most obvious. But their UX for visualizing interlinked structures and editing them are not enough. Probably some solutions may pop up as a result of hackatons such as https://mapsmap.devpost.com/ From starting points Observable took on Jupiter Notebook concept with added block links looks nice. However there might be a totally different set of tools for managing documentation maintenance complexity. Maybe the main feature of graph documentation editor should be not the UX, but live metrics.

Thanks for this very thoughtful post. I generally agree with the issues you identify. If I can rephrase your “structuring and arrangement” comment, I’d say our shortcoming is the curation of the documentation. We have good content, but it’s not necessarily arranged in a way where it’s easy to find. A librarian would do us a lot of good.

My first reaction was to be opposed to this, but I wanted to sit with it for a little bit, which is why I waited to reply. I think I like this approach the more I think about it. Historically, our documentation was more book-like (which could explain why we used DocBook XML for it) which is not necessarily a good fit for what people are looking for.

The introduction of the Quick Docs, which provide short, focused documentation has helped us. I think moving closer to that would be good. To wit…

… making our guides basically be a curated set of links to Quick Docs and similar would be a good goal. We could either have it be HTML hyperlinks to different pages, or have the content be modular and use Antora includes to present it as a combined interface. I see advantages and disadvantages to both.

1 Like

Like Ben, I was also feeling unsure at first about abolishing editions… but the more I think about it, the more I like that idea too. Especially because it reduces a notable amount of tedious administrative work to update docs for new releases every cycle, and I don’t feel like that work brings a lot of value to our workflow. (A big hat tip to the valorous efforts of those who have done this often thankless work for several years!)

I also feel like there is a lot of value in Quick Docs, and there might be a lesson we can take from Quick Docs to apply more broadly to our project-wide documentation strategy. But I am on holiday right now and don’t have the time to put together a more thoughtful reply than this.

One thing I have always felt we did not utilize effectively in Fedora Docs is how Antora manages components and modules of documentation. I fell in love with Antora over other tool-chains for this reason mostly. But I feel like our initial roll-out was too decentralized, and as such, content ends up getting lost. Perhaps we could centralize more content together in a single repo, and better organize it across modules. If we used a platform like GitLab, we could also have code-owners who could be auto-assigned for reviewing content from other modules (but I don’t want to derail this thread on GitLab vs. Pagure, it was just a thought).

2 Likes