search

FOSSRIT / tasks

Public ticket tracking system for tasks, planning, and strategy for FOSS@MAGIC efforts
https://github.com/orgs/FOSSRIT/projects/1?fullscreen=true
Creative Commons Attribution Share Alike 4.0 International
7 stars 1 forks source link

Creating a place for static data / info for FOSS@MAGIC #33

Closed jwflory closed 5 years ago

jwflory commented 7 years ago

Summary

It would be helpful to have a place to put static information that is helpful, relevant, and easily referrable to, for students, faculty, professors, and other participants in the program.

Analysis

This is part of prior discussion in-person, on IRC, and in email over the past few months. We have started using the fossbox-tasks issue tracker as a place to track the things we're doing in real life and close them when we're done. While this has seemed to be effective so far, the issue we face now is for things that aren't so dynamic, e.g. mapping out an entire spring semester with important calendar dates and times to remember.

Having this static type of information in an organized, easily findable format will be helpful to keep ourselves organized and help on-board future participants in the program by having this information available.

git library

One possible solution is having a git "library" of sorts that is curated by Markdown files. One benefit to this approach is that it lets us create text documents with this information that are easily editable and distributable. Most any git forge renders Markdown and there are also many tools that let us export this data to almost any format we like. The downsides to this are making it difficult for someone to make a quick or easy contribution without basic knowledge of git. This could accidentally make our data less accessible by blocking people who have a lot to contribute because of the technical barrier.

I created a mock proposal of what that might look like here.

Wiki

A wiki actually seems like one of the best solutions for this, but I am lenient to choose any option that would require us to have RIT ITS or other administrators involved to host the platform or remove control from faculty and students, because we have a strong history of bitrot with anything that has ever depended on RIT's infrastructure.

Examples

Examples of things we might want to keep in this repository…

Discussion?

Another concern I have is us having "too many places for too many things", and the sprawl ends up making it difficult to actually find things in the first place. We should be cognizant of this with whatever solution we end up choosing.

I would love to have feedback from a variety of folks on this topic to discuss what would be the best solution and how to make sure that this doesn't fall victim to being forgotten. We want to create a resource that people actually use and are easily equipped to support and maintain.

Thoughts?

cc: @Nolski @abkahrs @decause @FOSSRIT/foss-magic-faculty-and-staff

ryansb commented 7 years ago

Github has wiki functions builtin via gollum support, and you can clone the wiki locally if you want to edit raw markdown or add other static files. Perhaps a wiki on the fossbox-tasks repo would be the best place to have that content, and avoid adding another repo to manage.

jwflory commented 7 years ago

@ryansb Ahh, I didn't know you could locally clone GitHub wikis. I had considered it, but ruled it out because I had assumed there was no way to "port-out" from GitHub. I like this idea! 👍

Nolski commented 7 years ago

I def think a wiki (or maybe even a forum?) is a great idea. Wiki seems more conducive to creating tutorials for getting on IRC, getting started with vim, etc. On the flip side, forums seem better for discussion (although this might overlap with the email list) and I often times see tutorials stickied for forums.

I'm not a huge fan of a lot of FOSS wiki software out there as feature development and modernization seems to move at a slow pace.

Maybe hosting some forum might be nice?

jwflory commented 7 years ago

@Nolski What are your thoughts about the GitHub wiki? I'm less partial to a forum because I think (1) to continues to the growing issue of sprawling across too many places for someone to keep up, (2) we do a lot of that type of discussion in IRC or in person, and (3) the general mailing list ( #30 ) seems to meet this type of functionality.

Nolski commented 7 years ago

I think github's association to git and source control makes the barrier to entry for non-technical or really young students just getting started with programming might make getting started a bit more difficult, especially when the resource is all about getting started.

While it's still fairly new, the mailing list doesn't seem to have gotten any real use. As far as "keeping up", I'm not sure what would be needed to keep up with something like a wiki that is just a bunch of tutorials and getting started guides that we can point to. I don't really see it competing with something like a mailing list/irc.

xforever1313 commented 7 years ago

For wiki software options, I recommend DokuWiki: https://www.dokuwiki.org/dokuwiki

The main reason why I recommend it is since it does not require a database... unlike Media Wiki and other Wiki platforms.

There's also an oauth plugin that has a "Login with github" option: https://www.dokuwiki.org/plugin:oauth

Or if you're feeling really brave, a shibboleth plugin https://www.dokuwiki.org/plugin:authshibboleth

jwflory commented 7 years ago

@Nolski I can understand the technical association to GitHub that might make some people apprehensive, but I also strongly believe there is value in keeping where we do things and communicate things together. Now that I know we can pull the raw Markdown files from GitHub wikis, I prefer Ryan's idea of integrating the wiki into the FOSSRIT/fossbox-tasks repo just to keep it with where we have our discussions (and maybe changing the name of the repo to be something more generic).

I think the content we would be creating in a wiki would vary on experience level. Some things we put together might be focused towards "getting started" but other things included in the repository could be for a more advanced audience. The question to the point you raise is who do we want to contribute content? Even with a new member to the FOSSbox, I think the likelihood for them to begin contributing content early on is unlikely. But as far as consuming it goes, it's easy enough to send a link to a GitHub wiki page for someone to read quickly and easily.

@xforever1313 Do you know of anyone that offers hosted instances of DokuWiki for free? I'm not opposed to the idea, but I am just very partial towards making sure we create something that is easily maintainable or will continue to exist if a graduated student forgets to pay a VPS bill or loses interest in maintaining it. Fragmentation is one of my biggest concerns with choosing a solution.

xforever1313 commented 7 years ago

@jflory7 I do not know of any hosted instances of DokuWiki. The only hosted wiki services I have experience with is Wikia (which is painfully sluggish imo). Here is a list of a bunch of hosted wiki instances, but I have no experience with any of them: http://alternativeto.net/software/wikia/.

Something to consider RIT does have a Confluene instance:

General Use Wiki Space: This wiki request form is best for projects that are not associated with an official RIT course. General wiki spaces do not have a course number, and therefore have no students or instructors. Examples of general wiki spaces include wikis for club or student organizations, committees for university projects and initiatives, wiki spaces serving as a template for others to copy, and departmental documentation.

More info: https://wiki.rit.edu/display/ritwiki/Wiki+Request+Overview

though per comments in the original post, it does depend on RIT infrastructure, which may be a problem.

...

Going back to putting a wiki on GitHub, people are able to edit wikis without knowing any git in the web-browser. IMO, there is no more learning curve than editing a wiki with different wiki software.

Nolski commented 7 years ago

@jflory7 Yeah but who are they going to ask to get the link? Github is a place where we put all of our projects, all of our code, all of our issue tracking, and now our wiki? It's great that you get to stay on the same website but navigating through FOSSRIT's github page, trying to find the place we store our wiki content sounds like a mess to me.

Nolski commented 7 years ago

Perhaps we can make http://foss.rit (we should really support tls for that but that's another issue) be a bit more descriptive and have links to these sorts of things (1 click login for matrix-irc/telegram-irc, link to wiki, etc)

axk4545 commented 7 years ago

I like that idea

On Tue, Feb 14, 2017 at 11:46 AM, Mike Nolan notifications@github.com wrote:

Perhaps we can make http://foss.rit (we should really support tls for that but that's another issue) be a bit more descriptive and have links to these sorts of things (1 click login for matrix-irc/telegram-irc, link to wiki, etc)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FOSSRIT/fossbox-tasks/issues/33#issuecomment-279763606, or mute the thread https://github.com/notifications/unsubscribe-auth/ADUyLK3NsRv3960tDfRAph7AlpW_jPqsks5rcdpbgaJpZM4L9uIe .

ghost commented 7 years ago

Several points:

I've activated the wiki for my hfoss repo, in part because I had an immediate itch to scratch, in part to better inform me about how it works and how it fits into these larger questions. I am heartened by its use of common, simple markups (I say this as having used various mutually incompatible wiki markups over the last decade and a half: In comparison Markdown and even reStructuredText are so much more beginner friendly and offer a smooth learning curve towards very portable skills) and that there is a potentially free-standing FOSS implementation that we could migrate to. I'm not super excited about increasing the scope of our programming language dependencies with regard to Ruby but I'm not sure how huge a deal that is.

My personal to-do item here is to compare/contrast Github's wiki engine, Gollum, to what Gitlab offers, by looking at the RIT KGCOE Gitlab instance.

I applaud ongoing concern about centralization/single-vendor-dependencies. That said, I am also trying to limit my exposure to proprietary software in general, including proprietary (to use the GNU/FSF term) service as a software substitute (SaaSS). This leads me to a position of in for a penny, in for a pound WRT github, so long as we continue to look to how to migrate or federate or otherwise mitigate these proprietary dependencies.

I very much like the idea of making fossr.it more useable this way, including both an addition of 1-click links to our venues at the bottom of the first view, and then also in the Learn More view. In fact, if we could get a link to

http://webchat.freenode.net/?&channels=rit-foss

in there by this afternoon for the FOSSTalk round table that might be something we could show.

I'm taking that last point, then, back via

FOSSRIT/fossrit.github.io#6

ghost commented 7 years ago

Brief follow-up on this: I got the link to the IRC channel into fossr.it, but there continues to be some, uh, branding friction that, though suboptimal, I hope is something we could still, eventually, finesse.

Beyond that, here is the ritjoe/hfoss wiki.

I have also spent a few moments creating a GitLab-native wiki on a project in the Gleason School's GitLab instance (which I would link, but it can't easily be made publically-viewable as far as I can tell).

This helps reassure me that any wiki content we create in GitHub will not be locked-in to GitHub aside from establishing the URLs to them. It is less tied-in to GitHub than these issues are, and is about on par with the binding of any other URL to any commit or patch.

jwflory commented 7 years ago

Late reply for me here…

@Nolski I understand your thought about it being messy to have everything in one place. I feel like the point we're at is summed up accurately in this tweet: "Trying to make one tool do everything is a recipe for disaster. Having a lot of tools is a recipe with a disastrous number of ingredients." So we need to find a compromise perhaps by better establishing what our goals / needs are first, and then focusing on the tool we're choosing second.

For me, here's how I'm seeing it:

Goal / examples

Platform needs

A platform that best meets this goals in my mind is able to:

Maybe before going further, it would help to vet these points so we can choose the best solution for our specific needs. Comments and feedback welcome!

jwflory commented 7 years ago

Hey, just as some follow-up here, I needed to document something so I went ahead and used the wiki on the FOSSRIT/library repo.

If there's no objection to this, we can just start using that as a place to document things, but feedback is definitely welcome, especially with regard to the above comment!

jwflory commented 5 years ago

So, this issue is almost two years old now. :slightly_smiling_face:

I think the recent changes with the GitHub Pages FOSSRIT website (fossrit.github.io) is sufficient to close this issue. I forked @ct-martin's work from the RITlug website at ritlug.com for our site.

MAGIC administrators approved the use of the GitHub Pages site to maintain our own web presence (once again). I'm working with @itprofjacobs to update and revise the content currently hosted on the site in early 2019. There is static information about the FOSS program on the website, and room to expand with more changes later (e.g. exhibiting student projects and hopefully adding a new category for the FOSS curriculum).

Given the current context, I am closing this issue as complete. :clapper: