Discussion: Policy for external links in nix.dev documentation

[hsjobeki]

Recent discussions around external link contributions have highlighted the need for a clear policy on what types of external links are appropriate for nix.dev.

Currently, nix.dev includes external links to content not yet contributed directly to the project.

These links vary across two dimensions:

Source type:

• Commercial sources (company blogs, vendor documentation)
• Community content (personal blogs, community wikis)

Content type:

• Fundamental concepts that should eventually be documented in nix.dev itself
• Specialized topics that may not warrant upstreaming

Both dimensions have gray areas that make case-by-case decisions challenging without clear guidelines.

Goals:

• Establish a transparent, non-discriminatory policy for external links.
• Maintain nix.dev as a welcoming, community-driven resource
• Balance practical value to users against long-term documentation and maintenance goals. (Keep in mind external content can change and break without warning, while control also comes at maintenance cost)

Questions

Policy options to consider:

• option A: Allow any external link if the content provides clear value to readers, regardless of source
• option B: Exclude commercial links for fundamental Nix concepts; permit community links only when content cannot reasonably be upstreamed
• option C: TBD - hybrid approaches welcome
  Implementation considerations

If we allow one company's content, on what basis would we deny another's?

Without an explicit policy, we risk either:

• Being accused of arbitrary discrimination when declining future commercial links.
  Some form already happened here in #1192.

• Being unable to decline commercial content because "you allowed X, why not Y?"

How do we define "fundamental" vs "specialized" content?

Should we distinguish between commercial vendors who contribute to Nix vs those who don't?

What process ensures consistent application of whatever policy we adopt?

Should there be a review/sunset process for external links?

Discussion

Please share your perspective on:

• Which policy direction makes sense for nix.dev's mission
• Practical criteria for evaluating external links
• Enforcement mechanisms that are lightweight but effective

Comparison to other ecosystems:

Rust's official documentation contains no commercial links and is often considered some of the best technical documentation in existence. This proves high-quality docs don't require external (commercial) content.

Author opinion

Given recent community tensions around corporate involvement, maintaining strict political neutrality through a no-commercial-links policy is the most sustainable way to protect nix.dev from becoming a battleground for ideological disputes.
Companies have materially supported the ecosystem deserve recognition, but through dedicated channels (sponsors page, event credits, etc.) rather than embedded in technical content where it creates precedent for any actor with controversial goals to demand equal treatment.

Therefore I propose Option B:

• No non-community-links in floating text. Exceptions in explicit "further reading" sections.
• Zero-process, easy to implement

Community is defined as whether the link points to a site hosted on nixos org or the nix-community repositories.

Decision

(To be updated after community discussion)

[yukiisbored]

From my perspective, the existence of external links to commercial content is more of a "legacy" when nix.dev wasn't an official Nix project/first-party source but an initiative started by Cachix, hence the links to them.

We had a similar discussion when Determinate Systems wanted to promote their Magic Nix Cache here too.

IMO, we should have first-party documentation acting as a source of truth. Anything missing or anything incorrect should be treated like bugs in the software itself.

We should reduce our dependency on third-party sources.

When it comes to commercial content, I don't think it has a place here and it goes against our guidelines for writing clear documentation.

Linking to non-commercial content is a hard one. Ideally, linking externally should be avoided as it poses risks (e.g. interpreted as an endorsement, content changing out of our control).

Defining what's acceptable as an external source and what isn't is hard. There's no correct answer to it and despite our best efforts, someone will complain about how unfair the policy is.

Personally, I'd rather have missing/empty/placeholder pages sticking out as sore thumbs than linking out to external content since it could motivate someone to help and contribute the missing pages.

But of course, this would be harmful to the reader as they're met with an unhelpful page titled with what they're looking for.

[grahamc]

It seems so bizarre to me to not use the full richness of all educational and learning material available due to some hand-wringing about commercial or non-commercial or whatever. We are in a huge ecosystem of The Web, and it's free to take advantage of it.

The world is better for nix.dev to have the best material it can, and to reference external sources as supplementary material.

For goodness sake, imagine if the energy and heartache and words that has gone into this went into writing and improving the documentation? There are approximately more words in the first message here than have been written in documentation in nearly year.

[hsjobeki]

I've contributed extensively to the nix-documentation ecosystem. This discussion is also documentation work. It is about protecting what we've built. Which I think should be worth collecting some thoughts.

If others disagree on the risk, I'll drop it.
Moving on to other work.

[tfc]

But I genuinely care about the documentation quality and want to have a productive discussion.

We definitely share that goal. I understand the fear of documentation turning into a "marketing target," but I believe we can trust our ability to moderate. We don't need to preemptively block a resource just because it might be a slippery slope to spam. We can reject low-quality marketing PRs when they appear.

Also any external link undermines that we prefer version controlled content contributed, rather than links to enterprise blogs.

I view this differently. Linking to existing high-quality external content fills immediate gaps for learners while we wait for upstream docs to catch up.

Actually, your own article about the module system is the perfect example of this. It is excellent, helpful content that clarifies a complex topic. The fact that it is hosted on your personal/external blog doesn't diminish its value to a learner. It would be a loss for the documentation not to link to it simply because of the hosting location.

(Honestly) We can decide to allow all enterprises to add links. Then we only need to make case-by case decisions on the content.

Let's go with this. We can establish a baseline policy: Content quality > Host origin.
If a link provides genuine educational value and isn't just a product pitch, we accept it. If it becomes a problem later, we can tighten the rules then.

[tfc]

I've contributed extensively to the nix-documentation ecosystem. This discussion is also documentation work. It is about protecting what we've built.

Your contributions are highly valued. We are on the same page about wanting to protect the ecosystem's quality. However, I view "protecting" the documentation differently than "isolating" it.

Also any external link undermines that we prefer version controlled content contributed, rather than links to enterprise blogs.

Commenting on this specifically because it also seems to be the underlying principle of your suggested approach B which has been described in the initial post of this issue after the discussion already started:

I fully share the long-term vision: ideally, all core knowledge should live directly in the upstream documentation. That is the gold standard we are aiming for.

However, I am concerned that blocking links acts as a penalty for the reader, not as an incentive for the writer. Hiding a helpful external resource does not magically trigger the creation of an official documentation page. It usually just leaves a void.

From a user's perspective (especially beginners), an imperfect link is infinitely better than a perfect void.

I propose we look at it this way:

External links can serve as temporary placeholders or markers for missing upstream content. They highlight exactly where our documentation has gaps. We can allow them now to help users immediately, while acknowledging that the long-term goal is to replace them with official content. Let's not make "perfect" the enemy of "helpful".

If others disagree on the risk, I'll drop it. Moving on to other work.

Allowing high quality external links doesn't force us to accept low quality marketing campaigns, which would form the worst-case scenario that you described earlier.