Create FOSS@RIT runbook

[jwflory]

Summary

Create a new runbook documenting various parts of FOSS@RIT / FOSS@MAGIC, to reduce overall bus factor in our org

Background

This ticket comes from a few in-person discussions among myself, @itprofjacobs, @ritjoe, @whenbellstoll, and @Tjzabel. It is also influenced by @ct-martin's comment in #105.

In short, there is not a good place to look for how FOSS@RIT "works". We have discussed this in a few different forms over the years, like FOSSRIT/library, FOSSRIT/fossrit, and a few other ideas over the years. Now is the time we push this forward, given my time with RIT expires at the end of February. This issue is a long-term task tracker for me to track progress on documenting our community, infrastructure, and best practices.

Details

I intend to set this up in a similar fashion to RITlug's runbook. It will use Sphinx to build and generate HTML documents from Markdown source files. The documentation will be published on a ReadTheDocs site.

Later, I will update this issue with a high-level idea of the most critical components to document

Outcome

• Reduced bus factor of how to manage and engage in the FOSS@RIT community
• More clear direction on where to document and store important information about FOSS@RIT

[jwflory]

I put out a request for comments to the wider FOSS community on Discourse:

https://fossrit.community/t/request-for-comments-foss-rit-runbook/176

I'd appreciate if folks could take a look and leave some thoughts in that thread!

cc: @Nolski @Tjzabel @ct-martin @ritjoe @whenbellstoll @jrtechs @kennedy @10eMyrT

[jrtechs]

@jwflory This is a great idea.

Based on the things we learned from the RITlug run book, I would recommend that this runbook use the standard markdown language. I felt like using reStructuredText in the RITlug runbook was an unnecessary hurdle for new people looking to make contributions.

[kevinassogba]

Good point. I, for one, am not familiar with the reStructuredText. Using Standard Markdown is more inclusive.

Kevin Assogba M.Sc. Candidate in Computer Science Rochester Institute of Technology Rochester, NY 14623

On Mon, Jan 13, 2020, 12:15 Jeffery Russell notifications@github.com wrote:

@jwflory https://github.com/jwflory This is a great idea.

Based on the things we learned from the RITlug run book, I would recommend that this runbook use the standard markdown language. I felt like using reStructuredText in the RITlug runbook was an unnecessary hurdle for new people looking to make contributions.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FOSSRIT/tasks/issues/107?email_source=notifications&email_token=AKOD6LE6EAGOIR4OGK5V7ZLQ5SOK5A5CNFSM4KE653U2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIZQ2FY#issuecomment-573771031, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKOD6LDPL7HCN6BY26AM6R3Q5SOK5ANCNFSM4KE653UQ .

[ghost]

I'm a fan of Markdown, but my understanding is that it is better for formatting for display rather than semantics, but that reStructureText accomodates semantic markup needed by things like Sphinx.

I don't know if and how much Spinx can consume markdown directly, or if writing something in Markdown can contain enough information to allow a tool like pandoc or similar libraries to convert to rst as an intermediate format.

Markdown might be sufficient for what we need, but its not an entirely arbitrary decision.

[jwflory]

Yes! Some pages (like index pages) must be written in ReStructuredText, but I intend to write all content in Markdown for ease of use. I learned the same thing you did with RITlug's Runbook, @jrtechs.

Also, I anticipate this thread becoming very noisy over the next few weeks. Please leave feedback in the Discourse thread, this will greatly help me keep on top of everyone's feedback. I intend to use this issue for PR updates and progress reports.

[jwflory]

The above GitHub issues from the Runbook are what I identified as things I can document before I depart from RIT. For now, I'm using the above issues as close criteria for this issue.

[ct-martin]

@jwflory before closing this, we should also make sure the runbook docs are linked from the website README.md