IT documentation has a disease: in-text links. The disease-inducing thinking is quite clear: someone writing the documentation writes 'install the drivers for your graphics card', and then provides a link to how to install graphics cards because they saw others do that sort of thing. But once you accept the general rule - that instructions can contain links to other instructions inside the text - then the instructions which you link to may also contain links.

This tree-like setup of knowledge, with 'nested dependencies', works fine for computers, so computer-engineers may imagine that it works for readers too. People think they can write documentation about software because they understand it well, and don't realize that this actually makes them less qualified than someone who just picked up the basics yesterday. The more people learn, the less they can explain. Everyone succumbs to the disease in time.

So little by little, a dependency tree of knowledge builds up, until the installation instructions look like a labyrinth.

 1# Install Arch Linux Bro!
 2
 3You can do it in 10 minutes, bro!  It's like 300 words!  Just read, bro!
 4Can't you just read the docs?
 5
 6├── Format
 7│   └── File Systems
 8│       ├── Further Reading
 9│       ├── btfs
10│       ├── ext2
11│       ├── ext4
12│       ├── ntfs
13│       ├── xfs
14│       └── zfs
15├── Grub
16│   ├── BIOS
17│   │   └── Encrypted 
18│   │       └── boot
19│   └── EFI
20│       └── Encrypted 
21│           └── boot
22├── Grub2
23│   ├── BIOS
24│   │   └── Encrypted 
25│   │       └── boot
26│   └── EFI
27│       └── Encrypted 
28│           └── boot
29├── Graphics Cards
30│   └── Determining the Manufacturer
31└── Pacman
32    ├── GPG Key Management
33    │   └── PGP
34    │       └── History
35    │           ├── Key Types
36    │           ├── Tools
37    │           └── Usage
38    ├── Installing Packages
39    └── Uninstalling Packages

The naïve writer may just think they have written this:

1├── Format (2 minutes)
2├── Grub (1 minute)
3├── Graphics Cards (1 minute)
4└── Pacman (2 minutes)

Your 300-word article isn't 300 words if it contains links to required reading.

Before someone writes a link half-way through an instruction manual, they should stop and read the entire page which they want to link to, and ask themselves the following questions:

• Does the link have just what's needed, or 800 words which have no relation to the current article?
• Will the reader understand which parts of this new article they need to read in order to understand your instructions?
• Could the reader get by with one or two instructions from that article, rather than the entire thing?
• Will the reader need to read further links from within those articles?
• Could you just fucking not?

The Obvious Alternative

List all dependencies up-front.

Required Knowledge: Docker, Python packaging, Running Linux, graphics-card kernel modules

Looks a bit scary when written out, right? Might suggest some of the readers shouldn't bother? But it's honest. And if someone decides not to look at a project because they don't actually know what a 'package manager' is, then they have saved their precious time, and the project's maintainer has lost nothing.

N.B. - there's no suggestion or even a hint that people should not link to related articles. Links to related articles help people to know how to sharpen their understanding. But if you don't list the requirements up-front, then the reader doesn't know which links are 'related and helpful' and which are 'required reading (stop here and read everything before proceeding)'.

No Jacquaysing: Embrace Strict Hierarchy

If you can't understand X without Y, then Y cannot ask you to read about X. If you think someone needs to understand basic python commands before running Linux, then linking to a basic python setup will help the reader. However, if your 'basic python' article says you need to understand Linux then you have just inflicted 'the halting problem' on a reader, who will not only stop reading, but conclude that your writing must not be worth reading.

The IT Nexus

If this hierarchical knowledge tree existed, I don't know where it would lead. On Wikipedia, all roads lead to Philosophy, but that's the result of 'related concepts', not required reading.

Perhaps all software roads lead back to their own history. Perhaps all the later articles on docker would have to link to lxc, and articles on more advanced lxc usage would lead back to chroot. And so on, through the history of IT, until articles on how to construct a loom.

Perhaps it splits into distinct tribes of software, which coalesce into a handful of C libraries beneath it all.

Or perhaps each article will lead to a problem solving article, and if they all lead to more generic problem solving articles, then the nexus of all knowledge is a reboot.