Where to house editable version of report

[nshockey]

Nicole has suggested putting the text of the report in a .md file instead of using the Wiki. The upside of this approach is that suggested edits would create a pull request, so we could moderate the edits and publicly discuss our decision to integrate each edit or not. The downside is that it's not as intuitive a process for those not familiar with GitHub. @txtbks is that a fair explanation of this approach? Thoughts on the relative merits of each approach?

[char-siuu-bao]

@nshockey, @txtbks - This is a great point, however, I would still prefer it be housed on a wiki. The wiki is easier to navigate with the side bar in terms of usability, and as you've pointed out, is far more intuitive to edit. Also, an .md file it would be an extremely long file that is difficult to both read and navigate! It also requires having a better understanding of markdown than in the wiki version, which is quick to learn but again, there's a perceived barrier to entry.

For the wiki, we can still see each revision, compare versions, and also have the capability to revert to past versions if we need to! Which I think would be adequate for review purposes.

What do you think?

[txtbks]

@lorrainechu3n I see your points about the limitations of .md files, however we could pretty easily set it up to display in Github Pages, which could even make it easier to read and navigate, and give us much more control over formatting and design (you can use CSS to style it). Personally I don't think that learning wiki syntax is any easier/harder than markdown, although I see how there might be a greater perceived barrier to editing in GitHub, since the process requires a couple extra clicks. However, I think that the ability to moderate and collectively discuss changes is very important. It makes our decision making more transparent, and also ensures we can always keep the content aligned with our code of conduct and values (with a wiki it is far harder to ensure, no matter how quickly we reverse potentially negative changes).

I'm happy to help with putting together some resources to help people learn how to contribute in GitHub, and also to brainstorm ways for people to contribute in lower-barrier ways (for example emailing us proposed changes). We can also ask around to see about whether there's a better platform for moderated editing outside of GitHub. @nshockey what do you think?

[char-siuu-bao]

@txtbks, if you think that's best we can go with that! Emailing and raising broader topics of discussion through Github issues is already an option in the current contribution guidelines which we could obviously keep in the Github pages version. Let me know if you'd like to take the lead in setting it up, I'm new to Github myself and am not sure of the most efficient way of creating an easily navigatable Github pages!

[txtbks]

@lorrainechu3n Thanks Lorraine, that sounds good. I wouldn't say I'm an expert either, but I'm happy to help get it set up. Just would need to wait until end of next week after I've got the application and review processes up and running. Don't wait up though if you'd rather forge ahead! FYI there's more info here.

[nshockey]

I think it makes sense to hold off until late next week when we'll have reviewers' comments and nearly final text to plug in.

@txtbks would it be possible to have those how-to resources ready by the Tuesday after next.

[txtbks]

Sounds good. I mean the how to resources aren't going to be anything different than what we already are planning to put together for people to generally use GitHub, but I'm happy to adapt it to help people know specifically how to contribute in the context of this report. Let's talk about it on Wednesday after apps are launched!

[txtbks]

I've been messing around a bit in GitHub pages, and think we can definitely make this work from a technical perspective - though we will definitely need a clear set of instructions for editing. Wasn't able to get the stylesheet from opencon2017.org to import, so will need to build that. @lorrainechu3n is this something you've built in the past, or something you'd like to build yourself? If not mind sending along the following? (no rush at all!)

1. Hex codes for OpenCon colorscheme (logo teal, logo orange, text color, link color)
2. Font face for headers and paragraph text (and websafe alternatives if available too!)
3. Any other styling you'd like to see included!

[JosephMcArthur]

The Stylesheet for the current OpenCon site is here. That's the main theme file where what you've asked for can be found. For everything, a folder is here.

[char-siuu-bao]

Thanks @JosephMcArthur for linking the stylesheet and @txtbks for investigating how this will work on pages! I think the best use of my time atm is integrating feedback into the report and rewriting sections since we've already received some great/useful comments!!

[char-siuu-bao]

@txtbks @JosephMcArthur @nshockey I'm working on getting the report on Github pages here: https://sparcopen.github.io/opencon-dei-report/

Do you know of any good contribution guidelines I can model off of for contributing changes to a website? I was thinking we could also maybe encourage people to submit issues or suggestions via email: that seems more realistic to me then asking people to edit the copy directly and/or the HTML files themselves.

[JosephMcArthur]

That makes sense. You could make key editable pages for the site (like the report sections themselves) in Markdown, which is very human readable even without tech skills. If you go with HTML, one thing we do at OAB with our HTML is also separate text from tags a lot e.g

<p>

big bit of text goes here

</p>

Rather than

<p>text goes here</p>

Making issues for changes is an easier ask, and leaving an "email us your thoughts" fallback is also good.

[char-siuu-bao]

@JosephMcArthur Yes I think I'll make the primary ask email/creating issues just given the timeline. Can update with contribution guidelines next week!

[JosephMcArthur]

I'm a contribution to the discussion!

[JosephMcArthur]

Closing this now, seems like we've done all this!