-
Notifications
You must be signed in to change notification settings - Fork 1
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.
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
Create FOSS@RIT runbook #107
Comments
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 |
@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. |
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 ***@***.***> 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
<#107?email_source=notifications&email_token=AKOD6LE6EAGOIR4OGK5V7ZLQ5SOK5A5CNFSM4KE653U2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIZQ2FY#issuecomment-573771031>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AKOD6LDPL7HCN6BY26AM6R3Q5SOK5ANCNFSM4KE653UQ>
.
|
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.
|
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. |
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. |
@jwflory before closing this, we should also make sure the runbook docs are linked from the website |
This commit is a first-take at documenting the numerous intricacies of how the FOSSRIT GitHub organization works. It is a massive brain dump of the last 3-4 years of how I have maintained things. This is the first time most of this information has ever been public because it was mostly from a routine I created out of a habit that was constantly changing and evolving. _Anyways_, this is my attempt to slow the rate of change and create a more standardized way of how we make changes to the FOSSRIT GitHub organization. Ideally from this point on, changes to the FOSSRIT GitHub organization will involve discussion and updating documentation. Since this is a first take, I am curious for feedback on others on how understandable this is, or if anything comes off as needlessly complex. Closes #4. ALSO RUNBOOK v1.0.0 IS OFFICIALLY DONE NOW YAY!!!!!!! 🎉 Closes FOSSRIT/tasks#107. cc: @ritjoe @whenbellstoll @Nolski @Tjzabel Signed-off-by: Justin W. Flory <[email protected]>
This commit is a first-take at documenting the numerous intricacies of how the FOSSRIT GitHub organization works. It is a massive brain dump of the last 3-4 years of how I have maintained things. This is the first time most of this information has ever been public because it was mostly from a routine I created out of a habit that was constantly changing and evolving. _Anyways_, this is my attempt to slow the rate of change and create a more standardized way of how we make changes to the FOSSRIT GitHub organization. Ideally from this point on, changes to the FOSSRIT GitHub organization will involve discussion and updating documentation. Since this is a first take, I am curious for feedback on others on how understandable this is, or if anything comes off as needlessly complex. Closes #4. ALSO RUNBOOK v1.0.0 IS OFFICIALLY DONE NOW YAY!!!!!!! 🎉 Closes FOSSRIT/tasks#107. cc: @ritjoe @whenbellstoll @Nolski @Tjzabel Signed-off-by: Justin W. Flory <[email protected]>
This commit is a first-take at documenting the numerous intricacies of how the FOSSRIT GitHub organization works. It is a massive brain dump of the last 3-4 years of how I have maintained things. This is the first time most of this information has ever been public because it was mostly from a routine I created out of a habit that was constantly changing and evolving. _Anyways_, this is my attempt to slow the rate of change and create a more standardized way of how we make changes to the FOSSRIT GitHub organization. Ideally from this point on, changes to the FOSSRIT GitHub organization will involve discussion and updating documentation. Since this is a first take, I am curious for feedback on others on how understandable this is, or if anything comes off as needlessly complex. Closes #4. ALSO RUNBOOK v1.0.0 IS OFFICIALLY DONE NOW YAY!!!!!!! 🎉 Closes FOSSRIT/tasks#107. cc: @ritjoe @whenbellstoll @Nolski @Tjzabel Signed-off-by: Justin W. Flory <[email protected]>
This commit is a first-take at documenting the numerous intricacies of how the FOSSRIT GitHub organization works. It is a massive brain dump of the last 3-4 years of how I have maintained things. This is the first time most of this information has ever been public because it was mostly from a routine I created out of a habit that was constantly changing and evolving. _Anyways_, this is my attempt to slow the rate of change and create a more standardized way of how we make changes to the FOSSRIT GitHub organization. Ideally from this point on, changes to the FOSSRIT GitHub organization will involve discussion and updating documentation. Since this is a first take, I am curious for feedback on others on how understandable this is, or if anything comes off as needlessly complex. Closes #4. ALSO RUNBOOK v1.0.0 IS OFFICIALLY DONE NOW YAY!!!!!!! 🎉 Closes FOSSRIT/tasks#107. cc: @ritjoe @whenbellstoll @Nolski @Tjzabel Signed-off-by: Justin W. Flory <[email protected]>
This commit is a first-take at documenting the numerous intricacies of how the FOSSRIT GitHub organization works. It is a massive brain dump of the last 3-4 years of how I have maintained things. This is the first time most of this information has ever been public because it was mostly from a routine I created out of a habit that was constantly changing and evolving. _Anyways_, this is my attempt to slow the rate of change and create a more standardized way of how we make changes to the FOSSRIT GitHub organization. Ideally from this point on, changes to the FOSSRIT GitHub organization will involve discussion and updating documentation. Since this is a first take, I am curious for feedback on others on how understandable this is, or if anything comes off as needlessly complex. Closes #4. ALSO RUNBOOK v1.0.0 IS OFFICIALLY DONE NOW YAY!!!!!!! 🎉 Closes FOSSRIT/tasks#107. cc: @ritjoe @whenbellstoll @Nolski @Tjzabel Signed-off-by: Justin W. Flory <[email protected]>
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
The text was updated successfully, but these errors were encountered: