2023-05-04 Documentation team meeting notes #45

fricklerhandwerk · May 4, 2023, 5:28pm

Video conference
GitHub project board
Team details
Past meeting notes
Attendees: @fricklerhandwerk @infinisil @zmitchell @asymmetric @henrik-ch @j-k, and some others
Notes by: @infinisil

Agenda

Figure out what to do with how-to guides

What to do with all the guides

Examples:
@fricklerhandwerk: Move to nix.dev, but how to organize them?
@zmitchell: Goes into Add recipes, reference, and contributing sections by zmitchell · Pull Request #520 · NixOS/nix.dev · GitHub, can continue on that
- Recipes can be divided into:
  - Nix
  - Nixpkgs
  - Language-specific sections also make sense
  - Development environments
@infinisil: Move into flat structure, sort out later?
@asymmetric: Shouldn’t move until we have a clear position for nix.dev, still a separate domain, different from manuals
- @fricklerhandwerk: Discussed this before, can’t speed this up, let’s just assume it’s where people will end up
- @asymmetric: Can copy, but not remove it from the old locations, since it breaks workflows.
- @fricklerhandwerk: Won’t be a problem when nix.dev becomes official, should happen this year.
- @zmitchell: People generally know less about nix.dev, and it still looks unofficial. Landing page is a list of pages. Action items should be to fix these.
- @zmitchell: Should remove old locations but link to nix.dev. Indicate that it’s the direction we’re going towards, it won’t be an immediate change, very incremental. We don’t want people thinking we just remove docs.
- @fricklerhandwerk: Agree with all of that. What we need now is clear guidance for us (and later contributors) what we want things to look like.
@fricklerhandwerk: The question is: What’s the data type of a how-to guide?
- Tutorials are a linearisation of a DAG of knowledge and skills. Guides are more for use cases. E.g. could it make sense to have a database of how-to guides?
  - How to relate to reference material? Could we include items based on tags automatically?
  - Implementation doesn’t matter right now
- Use cases are random access
- @zmitchell: Structure in the most intuitive way, but have a tag system.
  - Start by looking at existing tutorials and how to categorize them. Similarly with guides.
Looking at some guides, what are Nix, NixOS categories?
- @infinisil: Not sure if categories work, tags seem better
@fricklerhandwerk: Brainstorming: Reference is API. Recipes/guides use pieces from different APIs and combines them together.
- Use cases could be purely Nix, or involve multiple different parts. Overarching themes maybe, like caching, remote building?
How to do tags with sphinx?
- @infinisil: Infrastructure question, could maybe even be filesystem based with symlinks
Let’s go through some guides and assign tags, as an exercise:
- Frequently Asked Questions — nix.dev documentation
  - nix, caching, nix configuration
- Frequently Asked Questions — nix.dev documentation
  - nix, nix configuration, caching
- Frequently Asked Questions — nix.dev documentation
- Debug a Nix expression with debug/trace statements? - #3 by bhipple
  - Nix language
- Installing only a single package from `unstable`
  - Nix language, Nixpkgs, channels
@infinisil: Let’s use tags, but need infrastructure for rendering it
- @zmitchell: Can use frontmatter for tags and put guides in a flat list for now
@fricklerhandwerk: Other generic information for guides: Prerequisites for using it, which tutorials in the “knolwedge graph”
- E.g. for Frequently Asked Questions — nix.dev documentation
  - Which file to edit? How to rebuild?
- Also: Make sure it actually works given only the provided information
@infinisil: To progress: Show how to have the flat list in nix.dev, just start with tags, might be enough to move
- @fricklehandwerk: How about documenting the ideal state of a guide so that you can look at that
A guide how to structure guides:
- make sure it’s actually a guide according to Diátaxis
- put each guide in a separate file in the recipes directory
- add tags on the topics or components it involves in the front matter
  - how do you know which tags exist and what they mean?
    - @zmitchell: Glossary, to make sure we don’t have different casings
    - @infinisil: Same as the glossary itself, not separate tag glossary/term glossary
    - @infinisil: Could also just let tags evolve naturally by reusing other tags
- add relevant tutorials as prerequisites in the front matter
  - this ensures readers are actually able to make use of the guide
  - do not need to write down the entire dependency graph, only those at the “leaves”
- Make sure the instructions work as intended
Should how to fix errors/troubleshooting be included in guides?
- @zmitchell, @infinisil, @fricklerhandwerk: Yes
@henrik-ch: Can we move bits from the wiki?
- @fricklerhandwerk: I thought we can, just have to attribute it correctly
- Looks like the wiki is actually MIT and copyright held by @Mic92: NixOS Wiki:Copyrights - NixOS Wiki
  - Could ask to relicense
@zmitchell: Regarding tooling there’s lots of sphinx extensions, but not a lot of them are packaged for Nix
@infinisil: Let’s maybe assign action items to members who aren’t here, more asynchronous

Action items

@fricklerhandwerk: Write out the drafted guide for writing guides
@zmitchell: Create an issue to figure out how to integrate tags into Sphinx