Request For Comments: FOSS@RIT runbook

RIT Academic Life
,
#1

Hi all,

This post is my proposal for a FOSS@RIT “runbook,” or documentation about how RIT’s open source community and infrastructure are run and managed. I will start building the runbook on Thursday, 16 January 2020.

Background: Why?

There is not a single place to look to find out information about RIT’s open source community. We have our website, but this is more for an external audience. It doesn’t explain anything about how we operate or how we are managed. So, a FOSS@RIT runbook would consolidate information about our community into a single place, to make it both accessible and also easier to maintain over time.

For background, this has been attempted a few times before without much success (mostly because nobody had time to lead on what is a lot of work). Here are some of the past attempts we’ve tried over the years:

https://github.com/FOSSRIT/fossrit

Documenting this info is important to make our efforts more sustainable and provide more in-routes for people to get involved and help with RIT’s FOSS community!

Details: Content

Content is divided into two different categories: community and infrastructure.

Community

Community documentation focuses on how the FOSS@RIT community is managed and operated. Currently, I see it including this content:

  • Governance
    • GitHub organization (@FOSSRIT)
    • Admin contacts

Infrastructure

Infrastructure documentation is technical writing that explains how to manage and interact with FOSS@MAGIC’s technical services we offer:

  • Ansible
    • How to use
    • How to gain access
  • Services
    • Discourse
    • IRC
      • Cloaks
    • Telegram
    • Matrix
    • Bridges (TeleIRC/Matterbridge)
    • Website
  • API/service accounts

Details: Implementation

I intend to create two git repositories using the Python Sphinx documentation toolchain: one for the community docs and one for infrastructure docs. The two repositories would be published on the ReadTheDocs.org site. The infrastructure docs would be “nested” as a sub-project underneath the community docs to improve visibility and connect the two repos together for a reader.

Why split them at all?

The community docs and infrastructure docs are maintained by different people. The community docs are likely to change less frequently and will be managed by FOSS@MAGIC payroll faculty. Separating the community docs into their own repository allows us to selectively ping folks for reviewing relevant changes. The infrastructure docs will likely change more frequently, and will be managed by infrastructure-focused FOSS@MAGIC payroll faculty and also Tech Team volunteers. The tech-minded folks will be pinged to review these docs, and the people who review community docs can choose to opt in or opt out to infrastructure documentation notifications.

Examples:

https://docs.thefutureis.science/en/latest/

https://docs.thefutureis.science/projects/poc-1/en/latest/

Expected outcome

A reduced bus factor in the FOSS@RIT community and more opportunities for people to get involved and participate in our community.

"Documentation is key for Inclusion" (and power distribution to a community)
#2

I encourage the initiative. It will help a lot of students willing to actively participate in the FOSS community at RIT. I would suggest forming a group of 3-4 people to work on it, because the load might become heavy on 1 person.

1 Like
#3

Hey @kta7930, welcome to the FOSS RIT community forums! :wave:

This is a good point. This will definitely be part of the volunteering initiative at FOSS@MAGIC this semester!

#4

One quick thing while I’m thinking of it, archiving old repos would be useful to indicate what isn’t active anymore and will not be getting updated docs.

Partly an aside, I also think there needs to be an on-boarding of people this semester to make sure there are humans who know how things work and keep the runbook useful; I’ve noticed with some of the RITlug runbook that things can get outdated if they aren’t actively being used, and trying to on-/off-board people is a great way to check if you have everything you need written down.

1 Like