Add Landing Page for Infrastructure Documentation

[JimMadge]

Summary

Contributes to #2809

Add initial section for documenting infrastructure processes/tasks/configuration.

List of changes proposed in this PR (pull-request)

• Add infrastructure section to the community hand book.

What should a reviewer concentrate their feedback on?

• Everything looks ok?
• Is this the most appropriate place
• Should we call this infrastructure?

Acknowledging contributors

• All contributors to this pull request are already named in the table of contributors in the README file.
• The following people should be added to the table of contributors in the README file:

Updates

I have taken out the documentation for the contributors record process (#3093) and force pushed so this PR is only the top level page for a new infrastructure documentation section.

I will open a PR for the other part separately.

[netlify]

✅ Deploy Preview for the-turing-way ready!

Name	Link
🔨 Latest commit	0d8efea
🔍 Latest deploy log	https://app.netlify.com/sites/the-turing-way/deploys/64830743754c350008439ae2
😎 Deploy Preview	https://deploy-preview-3102--the-turing-way.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[AlexandraAAJ]

All these changes look very good to me.

[malvikasharan]

Jim, I am a bit unsure what the contributors.md file in the infrastructure chapter is for. That repeats the information from the Acknowledgement chapter: https://the-turing-way.netlify.app/community-handbook/acknowledgement/acknowledgement-record.html
A point from style guide: when creating a subchapter, please use the chapter name as a prefix of the name:

• infrastructure.md
  • infrastructure-subchapter1.md
  • infrastructure-subchapter2.md

[JimMadge]

@malvikasharan yes I was worried about that. I definitely don't want to duplicate any information (at least not any more than is necessary).

I started with the contributors as an example as that was something I had just done, so I felt happy that I understood how it worked.

The idea is that infrastructure/infrastructure-contributors.md should talk only about the technical parts of how the contributors record gets made/updated. That way it is useful for anyone who wants to understand how it works or fix a bug. It shouldn't talk about other aspects like how to use the bot or the emojikey, for example.

I tried to keep that distinction clear but anything we can do to improve that would be good 👍.

[bsipocz]

@JimMadge - I know it's a draft just yet, but currently it's pretty difficult to review it as changes from #3093 is mixed in. Would it be possible to disentangle the two and have only the infrastructure relevant content?

[malvikasharan]

I see your point. This is definitely a good place to describe the weekly workflow of automated PR for Contributors file.

[JimMadge]

@bsipocz Not quite, sorry, bad manners on my part. I built this on top of that branch because I was going to describe the 'new' way the contributors record is built rather than describe the existing process that I'm proposing to replace 😅.

The two content changes are https://github.com/alan-turing-institute/the-turing-way/blob/f69c73f8359d4ee66afcb360fd57c2fa5cdad814/book/website/community-handbook/infrastructure.md and https://github.com/alan-turing-institute/the-turing-way/blob/f69c73f8359d4ee66afcb360fd57c2fa5cdad814/book/website/community-handbook/infrastructure/infrastructure-contributors.md (both new files). I hope that helps 🤞.

[JimMadge]

I see your point. This is definitely a good place to describe the weekly workflow of automated PR for Contributors file.

Great 👍, that is the kind of thing I was hoping to describe in this section. (Although, I'm proposing replacing that PR process in #3093 😅)

[aleesteele]

As I add notes, tagging #2337 here, as it is also tied to (on a conceptual level), discussions around how we define open infrastructure as a community. Thanks @JimMadge for creating this draft.

[malvikasharan]

Tagging @KirstieJane here for her points on the decision-making process for the infra teams.
What is unclear? What process have emerged that are being formalised? What are the blockers? etc. -- this info has been shared in the governance Survey that @aleesteele should curate and add below as comment.

[malvikasharan]

Also tagging @AndreaSanchezTapia here to represent the infrastructure requirements for the translation team who work on a fork of the repo for the translators.

Their governance at the WG level will look different as described here: https://the-turing-way.netlify.app/community-handbook/translation.html -- but can be used for reference to define the following:

• Infra WG roles and responsibilities
  • Leads: who has the overview of what is happening, what is the priority
  • Dependency maintainers: All-contributors bot, netlify and Jupyter Book maintainers in TTW (supporting the transition to new version - tagging @choldgraf)
  • Documentation building: Infrastructure documentation (such as the local deployment chapter by @arronlacey et al)
  • Additional feature requests: Adding hypothes.is, Plausible (analytics), additional package -- although I think this may need to be compatible with the JupyterBook plans -- so how to make decisions for what features can be added
  • Issues and suggestion facilitator: When topics like these appear, who ensures that decisions are made: Swap from Netlify to ReadTheDocs #2481 <-- this should be CM (@aleesteele) in my opinion, who facilitates RfC (via GitHub issues and newsletter) when any recommendations are made by the working group
    etc. etc.

Each role should have a clear pathway for how decisions within the WG are made, how community members are on-boarded in the work (which work) and the feedback process.
I assume that you all have discussed this, and have provided details either in your meeting notes or survey response. Anne will be documenting this for the infra team (and other WGs) and coordinate with you all to get your feedback -- and hope that can go on the chapter that is being documented here.

[da5nsy]

@malvikasharan - May I suggest that the meta-conversion around infrastructure governance be kept to #2690, and meta-conversation around planning documentation be kept to #2809, and keep this PR for discussion of the specific documentation that @JimMadge is writing?

@JimMadge - With this in mind, what do you think about renaming this PR something like "Add section landing page for infrastructure documentation section"? I'd personally recommend also spinning the section on the new contributors record documentation out into a different PR (perhaps even combining it with the one that implements it?) just to make it clearer what is happening in this PR. That also means that this PR won't be waiting on #3093 itself.

[da5nsy]

I really like this write-up - sets the scene very nicely.

[da5nsy]

Very nice! 🔥