2022 Summer of Nix documentation stream

toraritte · August 1, 2022, 11:02am

Timesheets

week of 2022/07/18

hours: 26

contributions:

activities:

lectures:
- Eelco Dolstra - The Evolution of Nix (SoN2022 - public lecture series)
learning:
- in preparation to make contribution guidelines consistent across manuals/resources (see more at item 2. in “contributions:” above)
  - how to build the nixos.org website, and how the corresponding NixOS/nixos-homepage repo is composed via Nix flakes
  - how to build the Nix manual from the NixOS/nix repo
- by researching “fetchers” for:
  - upcoming PR to update builtins.fetchGit
  - discourse post to unify info scattered across manuals and reconcile ambiguities (e.g., builtins.fetchGit vs. Nixpkgs’ fetchgit)

week of 2022/07/25

hours: 53 hours

contributions:

GitHub gist: Re-imagining the documentation for Nix’s builtins.fetchGit (that could serve as a template for other function docs)
Discourse: What does “warning: Git tree ‘/a/path’ is dirty” mean exactly?
Discourse: rev and ref attributes in builtins.fetchGit (and maybe flakes too?)
Github: Comment in NixOS/nix issue #5128
Stackoverflow: How do Git revisions and references relate to each other?

activities:

lectures:
- Armijn Hemel - The History of NixOS (SoN2022 - Public Lecture Series)
learning:
- Going through the source relevant to builtins.fetchGit (namely, libfetchers/fetchTree.cc,libfetchers/git.cc, libfetchers/github.cc, libfetchers/attrs.cc and some of the tests)
- Git internals (object model, references, revisions)

week of 2022/08/01

hours: 43

contributions:

activities:

GitHub reviews:
meetings:
- with Valentin Gagarin (fricklerhandwerk); topic: docs vision, concrete tasks
- group call: Summer of Nix 2022 - Documentation project
lectures:
- Jon Ringer - The Architecture and History of Nixpkgs (SoN2022 - public lecture series)
learning:
- How to review GitHub pull requests
  - GitHub: About pull request reviews
- GitHub: NixOS/nix pull request #6420
- Explore PGF/TikZ for illustrating aspects of the Nix ecosystem; see notes here
- notes while trying to define the term “Nix” in a pedantic way

week of 2022/08/08

hours: 32 hours

contributions:

ngi-nix/ngi_website_content PR Add documentation-related blog post #5

activities:

Miscellaneous:
- Cleaning up user studies / learning journeys
  - Correspondence after initial meeting with @fricklerhandwerk
  - draft clean-up of one
    - Not sharing original notes because they may contain personally identifiable information
    - @fricklerhandwerk This gist only differs from the one I sent you is that I removed my notes that contain verbatim copies of text from the transcript.
GitHub comments/reviews:
- comment on i18n #6842
- Link source to documentation
  - NixOS/nixpkgs issue links from manuals to source code #184982
  - NixOS/nix PR distributed-builds: add link to source #6564
  - check updates to PRs / issues or read them for the first time:
    - doc/manual: define {local,remote} store, binary cache, substituter · Pull Request #6870 · NixOS/nix · GitHub (check updates)
    - NixOS/nix PR doc: add install test info to hacking.md #6652
    - NixOS/nix PR Greatly expand architecture section, including splitting into abstract vs concrete model #6877 (check updates)
    - NixOS/nix PR [[WIP] add full descriptions to options in nix help #6874](([WIP] add full descriptions to options in `nix help` by whentze · Pull Request #6874 · NixOS/nix · GitHub)
meetings:
- discussing tasks to tackle right away and pain points regarding writing documentation (planning to capture it in a blog post)
- “trio-ing” with @ctem and @a-kenji about solving internationalisation (see NixOS/nix issue #6842 - i18n)
lectures:
- Valentin Gagarin - Flattening the Learning Curve (SoN2022 - public lecture series)
learning / research:
- for blog post for Summer of Nix website
  - sporadic (seemingly endless) note-gazing and -taking
  - google search knowledge representation
    - wikipedia Knowledge representation and reasoning
  - google search programming fearless experimentation
  - Software Carpentry
- for a blog post about using data science in Nix documentation
  - Going down the rabbit hole when organizing though for blog post in previous item.
  - Gist with resources investigated (not spending time to remove my obnoxious annotation attempts in bookmark names…)
  - handwritten notes
- planning a short(ish) Nix intro video, may become something else (handwritten notes)

week of 2022/08/15

hours: 19

contributions:

ngi-nix/ngi_website_content PR Blog post: Propose ontological enrichment of Nix docs and how linked data may help #6

activities:

meetings:
- 8/16/2022 16:00 EDT - AM team meeting
lectures:
- Domen Kožar - Nix Is Going Mainstream (SoN2022 - public lecture series)
work in progress:
- Transcribing user studies / Nix learning journeys (no link due to personal information still present; private repo shared with @fricklerhandwerk)

week of 2022/08/22

hours: 14

activities:

work in progress:
- Transcribing user studies / Nix learning journeys (no link due to personal information still present; private repo shared with @fricklerhandwerk)
lectures:
- Thomas Bereknyei - Hydra, Nix’s CI (SoN2022 - public lecture series)

week of 2022/08/29

hours: 21

contributions:

activities:

meetings:
- sync up with @fricklerhandwerk
lectures:
- Michiel Leenaars - The Significance of Reproducible Software in International R&D (SoN2022 - public lecture series)

edit: Apologies for the noise! Had to consolidate my time sheets because Discourse wouldn’t let anyone post more than 3 times in a row.