2023-04-20 Documentation team meeting notes #42

Agenda

  • updates
  • prepare agenda for 2023-05-27 hackathon
    • make sure there is a review pipeline
  • backlog grooming

Notes

Funded Project

  • @fricklerhandwerk: Have over 10k for the docs team, should go ahead and start the project.
  • @zmitchell: Maybe set up google form to find didactics expert
    • Need a way to onboard them.
  • @infinisil: Discourse post, like a job description.
  • @zmitchell: Set expectations, is it required to join the meetings, etc.
    • Job description usually include responsibilities, how many hours should be included and how they should be used. Coming to the meetings is a low bar
    • @fricklerhandwerk: Project plan is to create the schedule together, see https://github.com/NixOS/nix.dev/blob/f291daf90bbb270a0e74d68b5278908ffb8b3968/maintainers/google-season-of-docs-2023.md#editorial-lead. Definitely should have an initial talk to figure things out
    • @infinisil: Editorial lead for how long? Only one person?
    • @fricklerhandwerk: Gets us through the first month of the proposal.
      • Since @zmitchell runs the learning journey WG, editorial lead would be lead by the WG
      • @zmitchell: Not sure what my authority and boundaries are.
      • @fricklerhandwerk: Outline of the plan should be enough, questions can be discussed in the team, those who do the work take responsibility
    • @zmitchell: Expectations are important still, also for personal reasons
    • @fricklerhandwerk: How about writing something down for this to include in the project description?
      • @zmitchell: Thinking of an editorial lead, it’s about content and direction, but planning talks more about schedules, breakdown.
        • @fricklerhandwerk: Paid person should have responsibility to take care of logistics. Need to take time to get people onboarded, needs to coordinate with others.
      • @zmitchell: Have a didactics expert design the curriculum
        • @fricklerhandwerk: For that to work, needs contextual knowledge, takes weeks
        • @zmitchell: Is a month enough then?
        • @fricklerhandwerk: Not enough, but need to start somewhere. Outcome should be to write down what needs to be done, a project plan.
        • @zmitchell: Will it be implemented already or is it up to us to implement it afterwards?
          • @fricklerhandwerk: Won’t be enough time to implement
            • Best we can do is boyscout rule to the max: result should be a pile of everything that you encounter and learn and figure out
  • @henrik-ch: Do we have the full funds?
    • @fricklerhandwerk: Person would start until money runs out, continue when we have more funds
    • @henrik-ch: Might be hard to continue the work when passing the same position onto somebody else later
    • @fricklerhandwerk: Yes, same person should continue work later on if possible. We should make sure we get funding while work is still in progress.
  • @infinisil: Not sure if it’s a good idea to start already, funds will run out, a month passes fast, might not be able to continue.
    • @fricklerhandwerk: Will use it anyway at some point, would rather start sooner, also takes some time to start still, I don’t think it’s blocking
    • @zmitchell: By producing something with value, we could get more funding, that’s how grants work
  • @fricklerhandwerk: Idea: Flipped classroom, what would we want the editorial lead to do for us in the first weeks
    • @zmitchell: Look at the current learning journey plan and give feedback to it, could get help from the nix expert, figure out if it’s too much for a new student
    • @fricklerhandwerk: Not sure if they can answer this, even with an expert. Maybe assess how long it takes to complete the learning journey instead?
    • @fricklerhandwerk: Evaluate and revise the design approach.
    • @zmitchell: Are we expecting the didactic expert to be technical?
      • @fricklerhandwerk: On paper no, would get help from others.
      • @infinisil: I feel like it’s somewhat required to be technical, they’ll be involved in a very technical topic
      • @zmitchell: Agreed, not needed to be technical with Nix
      • @fricklerhandwerk: Experience with past UX workshop, which worked out well, despite the workshop leader Elton not knowing about Nix. Expecting for a didactic expert to be able to do something similar
      • Agreement it’s important, but not sure about it being a requirement
      • @infinisil: Depends on the person, if somebody has been doing this for a long time successfully without technical knowledge, might work
    • @fricklerhandwerk: How could an editorial lead relieve @zmitchell’s burden in the learning journey?
      • @zmitchell: Want it to be goal based (e.g. reaching a complete integration test project), they can help us determine whether goals are suitable, figure out pitfalls, whether it’s a reasonable goal.
        • Should show certain pain points, how to get unstuck, what amount of pain is appropriate in the journey.
      • @fricklerhandwerk: Should be a tractable task; figure out what’s too much, needs to be pulled apart, but no need to know too many technical details
    • @fricklerhandwerk: What if we invite the person you talked to on Mastodon
      • @zmitchell: Have talked to them before, but not sure if they have time, could ask them
      • @henrik-ch: Could also ask if they know someone
  • @fricklerhandwerk: Would it be useful to assess the use case we want to cover? Backwards design: Map out use cases, trace back steps to get there in terms of skills and knowledge. Requires figuring out where users come from. Would doing that be useful?
    • @zmitchell: Yes
    • @fricklerhandwerk: Can be done collaboratively between the editorial lead and the expert, with help of the team. Can collect material first and then go over it.
    • @zmitchell: Just talked about backwards approach in todays learning journey WG

Action Items

1 Like