Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CREATE: training-template repository #39

Closed
stefwrite opened this issue Oct 25, 2021 · 17 comments
Closed

CREATE: training-template repository #39

stefwrite opened this issue Oct 25, 2021 · 17 comments
Assignees
@stefwrite @tumido @HumairAK @4n4nd
Labels
area/community Indicates an issue/PR is related to the overall community. kind/documentation Categorizes issue or PR as related to documentation. kind/experience Indicates an issue/PR is related to human interaction and experience. kind/question Categorizes issue or PR as a support question.

Comments

@stefwrite
Copy link

stefwrite commented Oct 25, 2021 •
edited
Loading

New Repository

training-template

Repository description

This repository will serve as the template for our development spaces for training content that will live within Operate First.

Admin access

The same as the Operate First group admins + stefwrite (swatson@redhat.com)

Write access

The same as the Operate First group admins + stefwrite (swatson@redhat.com)
@stefwrite stefwrite added the kind/question Categorizes issue or PR as a support question. label Oct 25, 2021
@stefwrite stefwrite changed the title CREATE: of-training-template CREATE: training repository Nov 15, 2021
@stefwrite stefwrite changed the title CREATE: training repository CREATE: training-template repository Nov 15, 2021
@quaid
Copy link
Member

quaid commented Nov 15, 2021

This one didn't get any bot automation, not sure if that is normal or something didn't work?

So @stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

I'll take this out to the mailing list for some input from others for the best method.

@stefwrite
Copy link
Author

stefwrite commented Nov 15, 2021 via email

@quaid
Copy link
Member

quaid commented Nov 15, 2021

I dropped a summary to the mailing list with an invite for folk to come to this discussion.

Here is the email, and the body of my text:

All:

The team working on SRE training are ready to setup their repositories, and Stephanie created this issue for opening the first repository:

#39

We had a meeting today with the team who is going to be working in GitHub, and we're not sure what is the best model to follow for repositories.

Please join us there to discuss what we want the repo(s) to look like. We particularly need help from people with experience around automation across multiple repositories.

Background

Stephanie and anyone else, please fix any incorrect GitHub and modularity thinking here, thanks.

As a community, we are creating a knowledge pool of modular course materials. Modular here means, creating discrete pieces of content, each explaining what, how, and why for a task. The learner might be a contributor learning or reminding how to do the task; or the learner might be a user taking a full SRE course. The same content can be used in both cases, but placed into a context specific for the different learner type. This content therefore is more than a Markdown file, it has inline or metadata (labels, etc.) that means it can be organized to appear in multiple learning pathways.

These multiple learning pathways currently are: SRE Learners, Open Source Developers, Project Contributors, and Data Scientists and Data Engineers.

So if combining the pool with the number of learning path options, it could be four separate learning paths with e.g. twelve modules per path. Those modules would comprise existing modular content, combined with content specific to the module that shapes the relationship to the learner persona. An example of a single module might be, "How to use GitOps to make changes to a live production cloud." It could have the how-to and sparse-why content (useful for Project Contributors and Open Source Developers) from one location (a repo?), which can be combined with the full what/how/why of a beginner's viewpoint into a single ready-to-teach module.

That's already 48 unique combinations to cover four pathways, and within those modules it might be 3x to 5x more when combining pieces to form a specific module.

Is this a repos problem? A branching problem? A nesting folders problem? Or something else?

@HumairAK
Copy link
Member

I'm unfamiliar with this initiative so I'm looking for a bit of clarification here...

So @stefwrite and team are ready for a training repository, but it's not entirely clear what is the best structure to take for that. One repository per course? One repo that is just the Lego-bucket of content? Or do this all in branches?

What is the training content composed of? If it's jupyterbook/notebooks/markdown, why do we need separate branches or repos? Why not one repo with a directory structure for organization of different course content? e.g. openshift-labs.

Also why do we need another separate repo?

Will these training modules be using content completely in isolation from our other documentation? Example like here? If so then I suppose a separate repository make sense. If there's overlap, then I'd argue this content should be in the same repository for maintainability. Otherwise we're just going to have duplication of content being written by different folks.

Also...who are the target contributor demographic for these training modules? As an ops focused contributor, am I expected to take part here? If so I'd rather have this content alongside our other documentation under a separate training directory, so we have less repos to make PRs to when a procedure changes and it needs to be reflected in a 'how-to' style doc.

@stefwrite
Copy link
Author

stefwrite commented Nov 15, 2021 via email

@HumairAK
Copy link
Member

@stefwrite Thank you @stefwrite that clears up a lot of things!

Yeah if you're looking for 1 jupyterbook for 1 course, then in this case a repo per course is the easiest way to get started.

Can we have multiple build pipelines based on the same repository's contents?

ATM I believe we have 1 repo -> 1 build pipeline. @tumido @harshad16 can verify.

Though imho, having them all in one repo as part of the longer term roadmap makes a lot more sense to me. If for example, one link changes, having to make pr's to 10-15 repos sounds like a nightmare. And as you said, referencing across courses would be easier.

@quaid quaid added area/community Indicates an issue/PR is related to the overall community. kind/documentation Categorizes issue or PR as related to documentation. kind/experience Indicates an issue/PR is related to human interaction and experience. labels Nov 16, 2021
@quaid quaid mentioned this issue Nov 16, 2021
Closed
9 tasks
@quaid
Copy link
Member

quaid commented Nov 16, 2021

  • It's certainly possible to put everything into one repository (including all the graphics and audio that we typically include). The upside is that we can easily reference other content across the repository. The downside is that each new course we add will grow that repository and create for larger checkouts over time. At the moment, we're certain we'll produce 10-15 courses from our team, and we hope others will follow the model we set up to create even more.

One of the strange magics of git is how small a checkout is despite how large and old the repository is, right?

So it's possible that 15 - 30 courses is not that large of an initial checkout. Wherever possible, git is only tracking the difference between different commits and across branches, so each commit and new branch is not very large.

If you have a lot of large media assets (and especially if they are unique for each module), maybe there's some kind of lookaside cache that can be used, so the repo only holds pointers the actual asset in the cache?

@HumairAK
Copy link
Member

I confirmed with @harshad16 that it is actually possible to have multiple build pipelines associated with one repo, e.g. https://github.com/thoth-station/solver/blob/master/.aicoe-ci.yaml

@durandom
Copy link
Member

I suggest to start with one repo and see how complex it gets building multiple JupyterBooks.

Is operate-first/training a good name? If so @HumairAK can you create the repo and setup bot automation for it?

@durandom
Copy link
Member

And for access I suggest to create a training team

@stefwrite
Copy link
Author

stefwrite commented Nov 17, 2021 via email

@quaid
Copy link
Member

quaid commented Nov 18, 2021

And for access I suggest to create a training team

And an associated group of humans who meet regularly and drive progress transparently in the community, following whatever organizational structure we create in the coming weeks.

@HumairAK
Copy link
Member

HumairAK commented Nov 23, 2021 •
edited
Loading

Hey guys, I've added some docs on:

  1. how to add a repo
  2. how to join/create a team/get access to a repo

Anyone willing to try to provision this repo themselves using these instructions, would also find the feedback on the docs useful, so we can improve them :)

@quaid
Copy link
Member

quaid commented Dec 15, 2021

@coghlanRH and I are going to create this new repo training, thanks @HumairAK for the docs.

coghlanRH added a commit to coghlanRH/common that referenced this issue Dec 15, 2021
@coghlanRH
Added new training repo
bdc7685 
- Closes issue operate-first#39 
- As per the discussion in issue operate-first#39, we are going to start with one repo and
  have clearly named individual jupyter notebooks per course
@coghlanRH coghlanRH mentioned this issue Dec 15, 2021
Merged
@HumairAK
Copy link
Member

HumairAK commented Dec 15, 2021 •
edited
Loading

New repo created, thanks for the PR @coghlanRH ! https://github.com/operate-first/training

If you guys need admin access to this repo, you'll need to be in a GH team that has admin rights to the repo:
https://github.com/operate-first/common/blob/main/docs/add_gh_member_and_access.md

@quaid
Copy link
Member

quaid commented Dec 16, 2021

New repo created, thanks for the PR @coghlanRH ! https://github.com/operate-first/training

If you guys need admin access to this repo, you'll need to be in a GH team that has admin rights to the repo: https://github.com/operate-first/common/blob/main/docs/add_gh_member_and_access.md

Great, and thank you for the link to the docs!

@stefwrite has volunteered to do the updated to the OWNERS file, and we will probably also touch the README and contributors.md files.

@stefwrite
Copy link
Author

We have the repo we need, and the OWNERS file is up-to-date. Closing this out.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@stefwrite stefwrite

@tumido tumido

@HumairAK HumairAK

@4n4nd 4n4nd

Labels
area/community Indicates an issue/PR is related to the overall community. kind/documentation Categorizes issue or PR as related to documentation. kind/experience Indicates an issue/PR is related to human interaction and experience. kind/question Categorizes issue or PR as a support question.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@stefwrite @quaid @durandom @tumido @HumairAK @4n4nd