Discussion: Policy for external links in nix.dev documentation

Abierto
  • ¿Algo no está bien?
#1,194 6 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Documentación
Claridad
Necesita aclaración
Estado de actividad
Estancado
Área
documentation

Línea de trabajo

Comienza revisando los seis comentarios y el PR #1192 mencionado; después, compara las opciones de política y las preguntas abiertas del issue. El trabajo estará terminado cuando la comunidad haya llegado a una decisión y la sección Decision del issue registre la política adoptada y su proceso de aplicación.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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)

Lenguaje dominante
Nix
Estrellas
4k
Forks
343
Merge medio
1 d 12 h
PR fusionados (30 d)
14

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de NixOS/nix.dev

Todos los issues de NixOS/nix.dev

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.