As I’ve been contributing to the Nixpkgs documentation, I’ve been learning about our documentation infrastructure, the tooling and processes involved in it, and I’ve been observing multiple areas of improvement.
I started my contributions with a very specific scope, but that evolved into other things, and based on those observations and my own experiences, I created this vision document for a future I’d like to make real.
Based on the vision, I created a roadmap which can be viewed here.
This post is very light on specific details.
It really just sets a vision for inspiration and to work towards, and there’s a lot of work to figure out what work actually needs to be done.
The roadmap is a step towards that.
My purpose in posting this vision here is to:
- Make people aware that there’s at least one person thinking about these things and working on it
- Make people aware that there’s plenty of room for them to contribute (especially once you look at the roadmap)
- Gather feedback from folks to improve both the vision and the roadmap
Vision
There are two things I want to focus on: maintenance and usability.
My specific focus is on the manuals, starting with Nixpkgs, but some things touch other documentation fronts as well (such as nix.dev).
This is the vision summarised:
I think we will be in a good spot when people can access manuals that have up-to-date content, and provide multiple ways for users to consume and navigate their contents.
We’ll be in a great spot if the manuals provide a unified interface for users and allow them to discover additional or related information to what they’re reading.
Let’s look into all of these attributes more carefully.
Acessing up-to-date content
In their current state, the manuals are only updated whenever people remember to update them.
This means that the underlying code that is being documented can change, but the documentation will become stale if nobody remembers to update it.
To provide up-to-date content on the manuals, we’ll need to improve how we maintain the manuals, and pay off the “content debt” that we’ve accumulated over the years.
The maintainance bit is important, because it’s what will help us keep content up to date and up to the standards we set.
We can’t just keep accumulating debt and paying it off in batches, because it puts a lot of strain on the people who eventually have to do the paying.
Providing multiple ways for users to consume content
At the moment, the manuals can be consumed through a web document, with content all in a single page.
This is a good way to consume content for some users and use cases, but makes it hard or impossible to consume content in other ways.
For example, it has been reported that the manuals crash or severely slow down mobile phones, so this becomes an obstacle for people accessing information from those devices.
There has also been feedback that consuming the content in ebook format would be helpful.
This means that no matter what we do, providing single-page content should still be possible, but this shouldn’t prevent us from providing the content in different formats (multi-page, ebook).
It also means that we should look into alternative ways of consuming some of the content in our documentation.
A good example is noogle.dev which allows a different way to consume the Nixpkgs library functions.
Providing multiple ways for users to navigate content
This is related to the point above.
Since the content is only available in a single page currently, it’s difficult for people to situate themselves when reading content.
It has been reported that once they’re in the middle of the page, it’s hard for them to understand what section they’re in, and see at a glance other topics around that content.
Being only available in a single page also severely hurts the placement of manuals in web search results.
Giving users other options to navigate content implies we’ll make the manuals available in multi-page format, and also means we need to provide better ways to search content across the manuals.
This ties into both points below.
Unified interface
At the moment, each manual is served from its own URL and there is no way for users to access other manuals from the one they’re currently in.
The Nix manual is built in a different way than the other two manuals, and so their interface differ completely.
If we go a bit further, nix.dev has its own completely different interface as well.
The only “unified” interface in the manuals that we have is a version switcher which allows users to move between different versions of the manual they’re in, but we can do better than this, and at the very least make it easier for people to go from one manual to another.
A unified interface helps users navigate content more easily, and provides a familiar “anchor” even when they’re reading through different concepts (often in a learning scenario, so the familiar anchor is helpful).
Discover additional or related information
Since two of the manuals are provided in single-page format without search, users can’t easily search across all manuals for the information they’re looking for.
When a manual links to information in some other manual, the linking is done through an external link, which means that it could go stale (especially because the current link checkers we use don’t check that the specific “section” present in the link still exists).
As a concrete example, the Nix manual has a glossary of Nix-related technical terms, but this isn’t easily discoverable when reading information in other manuals unless documentation writers manually link terms to their definitions in the glossary.
We also have tutorials, guides, and how-tos in nix.dev, but this content can’t be easily discovered from the manuals unless (again) documentation writers do that manually.
We should strive to make it easier to link information together.
For example, Wikipedia’s page previews are an inspiring feature.
At the very least, we should be able to better verify that the (external) links between manuals are not stale, but being able to provide internal links with better discoverability doesn’t seem impossible.
Disclaimer
I’m posting this here to share this vision (and roadmap) with the community, but I’m a bit concerned with two scenarios:
- That other people read this, think “there’s someone working on this already”, and I end up becoming a blocker to getting any of this done.
- That other people who want to contribute to the same, opposing, or just related things, end up being pointed to me as a blocker to get their thing done.
I want to be clear that I don’t wish to become a blocker on both of these cases, or any other case for that matter. I’m 100% open to help coordinate efforts and provide feedback on other efforts, and unless there’s some obvious conflict I’ll keep working towards what I outlined here, but if you want to contribute anything related to documentation, don’t feel blocked by this vision or roadmap! If you want to work within its bounds I’d be happy to coordinate things, but I’m also perfectly happy adapting the vision and roadmap around what other people end up contributing.