2022-06-23 Documentation team meeting notes #2

Development Documentation
1

Attendees: @mat @fricklerhandwerk @thufschmitt @Mic92 @infinisil @domenkozar
Notes: @fricklerhandwerk

Agenda (60 min)

  1. decide meeting date and times (10 min)

    • four weekly meetings
    • bi-weekly after that
    • proposal:
      • Thursday or Monday, Europe afternoon
      • rationale:
        • most contributors from Europe and North America
        • team lead should always participate

  2. decide team goals (10 min)

    • proposal (based on meeting #1):
      • ease Nix learning, increase onboarding success and user retention
        • identify and collect the best learning material available
        • conduct user studies and surveys, maintain feedback forms for validation
        • regularly evaluate observations, prioritize tasks accordingly
      • improve organization of Nix knowledge
        • set up and maintain contribution guidelines and quality standards
        • increase visibility of best practices
        • ease navigation of documentation around user needs
      • lead, guide, and support community efforts
        • formulate goals and roadmap
        • make and implement strategic decisions
        • direct contributors and help getting their work merged

    make RFC with results

  3. meeting process (15 min)

    • proposal:
      • work in central repository
      • agenda items as GitHub issues
      • write meeting notes per issue in collaborative markdown editor
        • assign scribe
        • assign moderator to keep focus and schedule
      • assign tasks in new issues, make pull requests for immediate results
      • paste meeting notes as issue comment
      • link issue comments with meeting notes on Discourse
        • also hard copy?
      • invite people with open PRs to meetings

    update contribution guide

  4. decide communication hierarchy (20 min)

    • proposal: organize by rate of change
      • web site
      • documentation (working title: The Nix Book)
      • manuals
      • RFCs
      • Wiki
      • Discourse
      • Matrix
      • meetings and events
      • Summer of Nix

    write down purpose of each instance (see pull request)
    figure out strategy to place it visibly
    make RFC with results

  5. set agenda for next meeting (5 min)

Notes

  • @domenkozar
    • Will not have much time in the next month but want to commit to something
    • Should focus on a few things to keep scope narrow
  • @Mic92 state of NixOS Wiki
    • @fadenb is admin but not really responsive
    • Wiki runs on outdated version of mediawiki
    • Have a backup running just to be sure
    • A project of this size should have more people being able to actually do things
  • Meet on Thursdays 17:30 CEST
  • @domenkozar
    • “Centralized” is a vague term
      • Elaborate on what that means
        • Discoverability for users
        • Enforcing quality standards
  • @thufschmitt
    • Do goals have priorities?
    • Support seems the most important, team is not supposed to do the work but enable others
      • @domenkozar primary goal is to improve learning, knowledge organization is a tool to achieve that
      • Leading and guiding should be the reason to exist for all the Nix teams
        • @domenkozar we have two audiences: users and contributors
          • Have to consciously address them, separately
          • @fricklerhandwerk users are already contributors, but we could make that transition much easier
            • @thufschmitt It should be so easy to use Nix that users should not care to contribute
          • Goal should be to enable people to learn Nix without help in a couple of hours
            • Most people will give up after 4 hours if they’re not passionate
            • Team task should focus on actually improving user facing documentation, less on tooling or contributions
              • Companies will have to fund that work, the point of the team would be to do the work in an organized fashion
          • Definitely avoid tooling discussion
    • @mat
      • experience with commercial users shows people get lost very quickly
        • hard to even figure out how to pin nixpkgs
      • EU contact, like most laypeople, asked for high-level description of what Nix can be used for
        • More interested in potential, e.g. role for economy
        • No obvious resources available to answer that question
    • @domenkozar RFCs for organizational questions seem not helpful
    • Meeting notes on GitHub are awful (experience from UX meetings)
      • HackMD works well
      • @domenkozar eventually we will converge on one thing for all teams, use whatever for now
  • Keep The Nix Book repo for communication, rename it later
  • @domenkozar future teams will have similar problems, eventually we will probably have to figure this out centrally
    • Have sane defaults for setting up teams
  • @thufschmitt the diagram shows that given how things are organized, this is the natural flow of information
    • Set it up visibly, but not in a way that makes it looks scary, as a barrier to contribution
    • @mat should formulate it more lightheartedly, e.g. docs team works on discourse
  • @fricklerhandwerk 6 min over time, will do better next week
6 Likes