Agenda
- prepare briefing for documentation project
Notes
-
@zmitchell: contacted @tonyfinn, working on packaging the tags plugin
- prior discussion on documentation project planning
-
@renoire would like to take part in the docs project as a volunteer
-
@fricklerhandwerk: suggests we use first time joiner @renoire as a guinea pig for how well our project brief makes sense
-
@renoire: “Categorise existing documentation” is very broad
-
@fricklerhandwerk: Knowing where to put new documentation is tricky, need to know prerequisites, documentation category, etc
-
@renoire: You have a structure problem
-
@fricklerhandwerk: Existing tutorials are quite sparse in which materials they cover, we’d like to create a structured outline to enumerate which materials should exist
-
@renoire: can offer writing articles
- possible approaches we can offer:
-
@henrik-ch: An immediate contribution could be reading links from the documentation survey and contributing a short description
- Should have a consistent way of doing it
- Also dating each link, some are probably very old
-
@zmitchell: We could just create a small template at the top of the documentation survey
-
@renoire: Are there tools we use for authoring and suggesting edits? Edits shouldn’t necessarily go straight to GitHub.
-
@fricklerhandwerk: HedgeDoc for collaborative writing, then GitHub so we can work async
-
@renoire: Working with Numtide we argued over which approach is better. We used HedgeDoc, but there one can’t suggest changes. Eventually used Coda.io for commenting on changes.
- will provide some insights on tooling
-
@fricklerhandwerk: We don’t really have the budget to pay for commercial tooling or the bandwidth to adopt separate tooling. Have to deal with what we have, but interested to take a look at the comparison.
-
@fricklerhandwerk: takeaway: we need to take more care on the technical side regarding how content gets into the respective repositories
- Editorial lead will probably ask similar questions
- How do manage a huge table like in #288, or the huge graph in the vision diagram? Existing tooling is obviously not ideal.
-
@zmitchell: Example: The nix.dev live reload script also doesn’t always pick up changes, have to do a full rebuild
- Collaboratively edited the project brief
Action items
-
@henrik-ch: Create a template for expanding on documentation survey items
-
@renoire: Provide some summaries on survey items
-
@fricklerhandwerk: paste today’s results into the project description
2 Likes
Hosted by Flying Circus.