name and place for central learning resource

[fricklerhandwerk]

given the goal of establishing a central learning resource, what should we call it?

• use nixpkgs.org or nixos.org
  • related: Figure out a pattern to break-out a NixOS Linux distribution "sub-site" (again) nixos-homepage#633
  • nix.org is currently being squatted on
    • @edolstra any chance of appropriating it?
• proposals for subdomain/repository:
  • documentation
  • learn
  • doc
  • docs
  • book
• ask domain owners to create/rename/reroute
• rename this repository accordingly, prefixed with nix-

[fricklerhandwerk]

• @domenkozar call it docs.<domain>.org, don't care about domain
  • separate components should have subdomains, e.g. nixpkgs.nixos.org
    • @fricklerhandwerk still leaves confusion around component names:
      • unified product and story #290
      • establish nomenclature #275
  • @infinisil does that mean to also move the Wiki into a subdomain such as wiki.nixos.org?
    • @fricklerhandwerk yes
  • @edolstra the domain is not a title
    • @domenkozar project should be "documentation team"
• @infinisil the name is not really important, content matters
  • @fricklerhandwerk we need a stable name to point people to something
  • @thufschmitt it should be just generically (the Nix) "documentation", as it covers everything
    • @edolstra completely disagree, calling it generically will only add to the confusion over the amorphous state we currently have
      • should be "The Nix Book" we can point people towards for learning (or doing something specific)
      • @domenkozar should there even be a Nix Book?
        • @edolstra yes, that's the component still missing in documentation
        • @fricklerhandwerk contents of this repository should be the book (or whatever we call it), team working here is about documentation in general
• @domenkozar why not just use nix.dev and build on top of that?
  • has tooling and is indexed well
  • @fricklerhandwerk don't care what we call it. would like to build on the core of contents from nix.dev, as it is of stellar quality, migrate in suitable material from NixOS Wiki, and add structure and process to enable contributions that raise coverage and quality
  • @edolstra nix.dev does not cover Flakes, a new documentation should start with Nix 3.0
    • @domenkozar Nix 3.0 does not exist yet
    • @fricklerhandwerk teaching Nix 3 CLI and Flakes #281
  • @edolstra nix.dev should be transferred to the community if it were to become the official learning resource
• @infinisil we could include projects from nix-community into official documentation
  • @edolstra ideally home-manager should be promoted to be an official Nix project
• @infinisil not clear what exactly we are doing as a team
  • collect (link to) or maintain resources?
  • @fricklerhandwerk take responsibility of known-good material, move that to a central repository (establish a single source of truth), and direct and enable contributions to that
    • (@domenkozar and @infinisil leave, 5 min over schedule)
    • @ryantm documentation should be close to the source
      • @fricklerhandwerk we have different levels of detail, and the manuals neither have structural nor maintenance capacity for what NixOS Wiki and nix.dev currently cover
        • have to make a practical trade-off where to separate responsibilities
          • scope of contents and team efforts #296

[fricklerhandwerk]

looks like there is no clear consensus.

proposal:

• rename this repository to documentation
  • The Nix Book in a directory
  • README.md show a very general overview
  • CONTRIBUTING.md deals with documentation team structure and contributing guides to the book
    • team is responsible for documentation experience with Nix and (to a lesser extent) nixpkgs
      • see scope of contents and team efforts #296
• set up docs.nixos.org and documentation.nixos.org to point to this repository
  • later set up proper rendering
• decide on https://github.com/NixOS/nixos-foundation/issues/34 and change accordingly

@domenkozar @Mic92 @edolstra @infinisil @thufschmitt?

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-06-30-documentation-team-meeting-notes-3/20055/1

[domenkozar]

looks like there is no clear consensus.

proposal:

• rename this repository to documentation

  • The Nix Book in a directory

  • README.md show a very general overview

  • CONTRIBUTING.md deals with documentation team structure and contributing guides to the book

    • team is responsible for documentation experience with Nix and (to a lesser extent) nixpkgs

      • see scope of contents and team efforts #22

• set up docs.nixos.org and documentation.nixos.org to point to this repository

  • later set up proper rendering

• decide on project domain name #23 and change accordingly

@domenkozar @Mic92 @edolstra @infinisil @thufschmitt?

What is the advantage starting over instead of improving https://nix.dev?

[fricklerhandwerk]

What is the advantage starting over instead of improving https://nix.dev/?

Materially, none, and I certainly don't want to start over. This here is just about the name (and location), and as @edolstra pointed out, ownership.

@domenkozar would you be willing to move the nix.dev GitHub repo into the NixOS organization and grant admin permissions to the documentation team? Then we could continue from there. (Side issue: Domain ownership and who pays for it. That should be discussed on the Foundation board.)

proposal:

• make nix.dev the central learning resource
  • (possibly make it the answer to NixOS/nixos-foundation#34: web site on nix.dev, documentation on docs.nix.dev)
• use the nix.dev GitHub repo for documentation team work
• migrate the notes, merge this repo's history into nix.dev and scrap this one

[thufschmitt]

(possibly make it the answer to https://github.com/NixOS/nixos-foundation/issues/34: web site on nix.dev, documentation on docs.nix.dev)

I have a hunch that using a separate domain for the doc and the website would be very annoying. So I think using (a subdomain of) nix.dev for the documentation would require making this the official website indeed

[fricklerhandwerk]

• @fricklerhandwerk what about making nix.dev making the project home page?
  • @domenkozar spent a lot of time on SEO, moving that will lose a lot of online reputation
    • built integration to make sure commands actually run
    • converted everything to markdown
    • starting from scratch is a bad idea
    • would not give out access liberally, better to see gradual process and see who gets involved in documentation effort
    • aware that people from Summer of Nix will come and add contributions
      • do not know their style of writing
      • do not have documentation to write documentation
        • @fricklerhandwerk establish writing standards #280
    • currently contributors have to assign copyright to me
      • idea was to publish a book eventually, dead tree publishers will complain when authorship is unclear
        • the point is to have authorship assigned to a single entity to not preclude publishing
        • can be ultimately transferred to Foundation
          • @fricklerhandwerk should be done immediately, e.g. "by nix.dev authors" and link to contribution graph
        • @infinisil proper attribution is important, we should not work around that external limitation
          • @j-k there are self-publishing services for that
            • @domenkozar it's a niche market with arbitrary prices and terms
          • we still have git commit history and we can show all contributors in the book's body
    • would rather focus on writing better resources than fighting the fight what is the official resource and such things
      • @infinisil indeed, that should be the marketing team's or the Foundation board's responsibility
        • @fricklerhandwerk yes, we have to assume users come to our resource, and it's the marketing team's job to make that happen
          • @domenkozar we should think of this as an organic process: we will write more docs, people will come, we will improve
      • once we start writing and organizing, things will crystalize anyway with user feedback
  • @infinisil we need a place to work, it does not matter what it's called
    • nix.dev already exists, we can move it later if needed
    • @domenkozar @fricklerhandwerk agreed
• @fricklerhandwerk what about calling nix.dev The Nix Book?
  • agree with @edolstra that we don't have that central resource with a sticky name
  • @domenkozar people have strong preconceptions about what a book should be
    • right now it's called an opinionated guide
      • people say that's exactly what they want
      • shows best practices and lists antipatterns
      • also some people disagree openly, but that's why it's an opinion, it's not supposed to be universal
      • @fricklerhandwerk definitely should offer best practices even if opinionated
        • we could gather more experience from prolific community members and seasoned developers
    • not convinced, because it's not really in the format of the book
      • like to call things what they are
      • once it's close enough to a book would call it a book

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-07-07-documentation-team-meeting-notes-4/20198/1

[fricklerhandwerk]

@domenkozar to migrate issues nix.dev has to be in the NixOS GitHub org, and probably I will need permissions.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-07-14-documentation-team-meeting-notes-5/20341/3

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-34/20901/1

[fricklerhandwerk]

To conclude, we decided that nix.dev is to be the central work place of the documentation team and the place for authoritative learning materials. This is yet to be made official:

• assign copyright to NixOS Foundation #262
• make nix.dev official nixos-homepage#882