# 2023-02-23 Documentation team meeting notes #29

**URL:** https://discourse.nixos.org/t/2023-02-23-documentation-team-meeting-notes-29/25731
**Category:** Documentation
**Created:** [February 23, 2023, 6:32pm UTC](https://discourse.nixos.org/t/2023-02-23-documentation-team-meeting-notes-29/25731 "2023-02-23T18:32:32Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![fricklerhandwerk](https://discourse.nixos.org/user_avatar/discourse.nixos.org/fricklerhandwerk/32/2029_2.png) [@fricklerhandwerk](https://discourse.nixos.org/u/fricklerhandwerk)
#### Post date: [February 23, 2023, 6:32pm UTC](https://discourse.nixos.org/t/2023-02-23-documentation-team-meeting-notes-29/25731/1 "2023-02-23T18:32:32Z")

</div>

Attendees: @olaf @fricklerhandwerk @pennae @stefanschroeder (later: @infinisil)

## Agenda

- finish the announcement
- find time for a working session
  - [Nix documentation team working session - When2meet](https://www.when2meet.com/?18874680-medDc)
  - **anyone interested in participating is invited to add their availability**

### Postponed to next time

- get back to a board-based workflow
- collect major goals as GitHub issues and bake them into the team handbook

## State of NixOS manual

- @pennae: only [worked on rendering](https://github.com/NixOS/nixpkgs/pull/217342), not contents
  - NixOS release notes editing process has been working quite well
    - may be enough to have that if we don’t manage to find a full maintainer

- @olaf: there is a lot to do, and a proper rendering infrastructure would help to make changes
  - nix.dev proved to be a good starting point to find smaller projects
    - example: [NixOS VM testing](https://github.com/NixOS/nix.dev/pull/334)

  - wouldn’t know how to get a PR to the NixOS manual reviewed
  - if we followed [Diátaxis](http://diataxis.fr/), we’d have to reduce the amount of material in the manual
    - but cannot just remove it, but have to find a new place and then remove it from the manual

- @fricklerhandwerk: agree with everything above
  - would like to get this team to focus on recruiting maintainers, and editorial and technical leads to work on the issues that are most pressing
    - most importantly we need someone for each manual to know the whole thing and have a vision, and spend the time to draft a migration path from here to there such that anyone can pick up chunks of work according to their capabilities

## Drafting the announcement

- [HedgeDoc - Collaborative markdown notes](https://pad.lassul.us/X5EMkmNARSSVOMcfrbhHvw#)
- (some debate on who exactly to address)
  - @fricklerhandwerk: we need both code owners as well as regular contributors
  - @olaf: yes, there should be a distinct group of team members other contributors can rely on to make decisions and create a coherent vision
  - @infinisil: not the last announcement, should start with owners
  - agreement

- (worked on clarifying team’s near-term goals)
- @fricklerhandwerk will make a review pass and together with @infinisil make the draft ready for publishing

## Feedback

- @stefanschroeder: observed a quite high-level discussion on vision, and it’s good it’s happening
  - given the amount of documentation out there, expected the team would have a more established, agenda-based, itemised workflow
    - @fricklerhandwerk: we’ll get back to that once we get back on track organisationally
      - separating administrative and productive tasks makes sense, and having two sessions per week would be ideal for that

  - propose to do research on existing materials and improve manuals and tutorials from there
    - @fricklerhandwerk: yes, [prior art here](https://github.com/NixOS/nix-book/blob/7fa972bc6e9f33b1827a5c4bdf03bdeb1ec00738/resources.md)
      - last year we only managed to agree on a very shallow ad-hoc roadmap, but we got things done
      - hope to return to building and following a more deliberate roadmap and quickly delve into making it a reality

- @pennae: can only contribute technically, but not take ownership of contents
  - @fricklerhandwerk: thank you so much for your work, your technical contributions are invaluable
    - hope we can continue collaborating async