Discussion: Policy for external links in nix.dev documentation

Aperta
  • Qualcosa non va?
#1,194 6 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Ferma
Ambito
documentation

Direzione di ricerca

Inizia esaminando i sei commenti e il PR #1192 indicato, quindi confronta le opzioni relative alla policy e le questioni aperte nell'issue. Il lavoro sarà completato quando la community avrà raggiunto una decisione e la sezione Decision dell'issue avrà registrato la policy adottata e il relativo processo di applicazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

tracking

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)

Lingua principale
Nix
Stelle
4k
Fork
343
Merge medio
20h 27m
PR unite (30g)
10

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di NixOS/nix.dev

Tutte le issue di NixOS/nix.dev

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.