Find/Write/Promote Simple Howto on Editing Text on GitHub

[mgifford]

I don't know if folks know how totally simple it is to edit these pages and propose a suggestion. I know that @laurawesley has done work for promoting GitHub for non-technical folks, but would love to see more folks inside & outside of government proposing ideas here. I'm worried that people may be intimidated because they see GitHub as a code thing not a version control thing.

Having something on the Readme to invite people to edit & make pull requests would be good. Providing links to video tutorials demonstrating how super simple it is to edit text in GitHub I think is going to be important here (and in future consultations).

[RussellMcOrmond]

In this case some guidance on what they are looking for. I haven't sent a PR as it isn't the same editing a whitepaper as it is code or documentation of a group with a shared goal. If a group was co-authoring a submission to government then the goal of the editing would be more clear.

[MaryBethBaker]

Hi @smellems,

I submitted a pull request with some very basic changes to the Introduction. Let me know or @RachelMuston know if you have a How to contribute section ready for the Readme documentation. I can help with uploading or even translation.

Hi @mgifford. Good point, I'm certain that another government or civic group has created a video or tutorial for non-technical people to edit. We just need some time to find it, or some one to suggest it.

Hi @RussellMcOrmond Have you forked the repo? Or are you more interested in submitting your comments as Issues that can be discussed? Perhaps this is a solution to group editing that would make more people comfortable before they submit their first pull request to the master repo.

I submitted a Pull request, but there is some wording and questions I have that I think would be appropriate for an Issue. Also this will allow us to have evidence of why we came up with the decision to keep or change a particular section/wording or nuisance.

Glad to see all this interest. Also impressed that the copy I had printed to read is already out of date. Straight to github for me now.

Mary Beth Baker

[MaryBethBaker]

@mgifford @smellems What about documentation similar to this?

https://github.com/canada-ca/code-with-us.wiki.git

/cc @RachelMuston

[smellems]

Hi @MaryBethBaker The link does not work (unless I want to clone your wiki)

I found this https://github.com/canada-ca/code-with-us/wiki/2.--How-to-get-setup-in-GitHub-%7C--Comment-d%C3%A9marrer-au-GitHub

It points to the Github Help. I also like the Github Guides, that has a "mastering Markdown" section, the problem is that they're only in English..

We definitely need something in the how to contribute section. Happy to see people collaborating already :)

[MaryBethBaker]

Hi @smellems,

Our section intro is in French, but you're right the github help and guides is in English only. Are you on the Github group for Government? Maybe you could inquire there about multilingual content.

[RussellMcOrmond]

@MaryBethBaker I've not submitted a pull request as I don't yet have a sense of the goals of the document. I don't want to be editing someone else's words without knowing those goals, and knowing my edits will be seen as improvements rather than contradictory.

One area I think needs improvement is the "Licenses" section of 4_Open_Source_Code.md

Different licenses exist to achieve different policy goals, and there should be guidelines drafted for which licenses can best achieve different government public policy goals. There is no "one size fits all", as each project will have its own goals.

Sometimes the public policy goal of a government initiative will be complimentary to the policy goals of other entities in the public or other sectors (including specific private sector businesses) and sometimes they will not. The private interests of a specific external entity should not override the policy goals of the government, except in very specific documented exceptions where that entity is necessary to achieve the public policy goal.

Example: Most modern operating systems have one or more application repositories to allow computer owners to easily install and update applications. While nearly all repositories are license agnostic, Apple has chosen to express a strong political opinion by denying code licensed under reciprocal licenses such as the GNU General Public License from their application repository. Apple has also made it hard for device owners to change or add other repositories. As it would be improper to allow Apple to dictate public policy to the Government of Canada, it would be improper to allow Apple's political campaign against a popular class of licenses to have undue influence on decisions made by the government of Canada.

---

The current early draft paragraphs look familiar to policies I saw within small companies in the 1990's, deferring most decisions to larger external entities. The Government of Canada is a much larger entity, has a larger public responsibility, and should be working on more robust guidelines for departments and agencies.

I've been working in FLOSS since 1992, consulting in the years since for many sectors including multiple government departments, so have participated in many processes to determine licensing.

[MaryBethBaker]

@RussellMcOrmond and @smellems Should we start with an issue on Licenses? I think @RussellMcOrmond you have some valid points about robust guidelines that we could learn from.

As a next step maybe people could use section numbers in their issue names or we could use the tags to keep conversations around each section sorted.

Happy to see all this work open and comments coming in, but I do agree with @RussellMcOrmond it would be good to add a set of objectives in the Readme so that we can use this to help us mitigate between opinion, influence and measure against the objectives when accepting or not accepting pull requests.

Thoughts?

Mary Beth Baker

[nschonni]

Not sure if it's the right solution, but I looked up http://prose.io again since I remember it had something for GH and multilingual pages (without a more involved Jekyll setup). I'm not sure if we rejected it the past for a particular reason (a11y, UX, or something else).

[laurawesley]

Yes please @nschonni Let's add prose.io!! We had tried it in the past...it only works on modern browsers and some people thought that was exclusionary. Personally I voted for it because it doesn't exclude use of a PR, it adds another way for people to comment while maintaining version control.

So happy this is happening! Thanks all

[nschonni]

OK, I'm playing with http://gitbook.com right now. I thought it might be a better fit for the whitepaper format, plus it's supposed to have multilingual support

[mgifford]

I wrote this up (using GoogleDocs) this morning https://goo.gl/gRHzDr

It should be reasonably simple with anyone using either Firefox or Chrome. I haven't tested it in the "annoying browsers". It probably works the same then.

The less software folks need to make these changes the better I find. Not sure how much extra is needed for Prose.io.

[MaryBethBaker]

@mgifford I tried it in the browser you mentioned you didn't use for testing. It all shows up.

[MaryBethBaker]

@Acasovan @smellems Should we translate and link to the google doc? Or make it another markdown page?

[mgifford]

@MaryBethBaker would be great if it were all in GitHub using Markdown so it could be maintained more easily. I just wanted to throw something up there so that there was an easy example of the simplest way to do this. I'd love to see a lot more policy development work done on GitHub, so it has to be simplified so that non-techs aren't intimidated.

[MaryBethBaker]

@mgifford great suggestions. I was wondering if there's ever been a civic tech presentation on GitHub possible for people to come out to in the future. It would also be nice to meet some of our collaborators.

[MaryBethBaker]

Ops... didn't mean to close this issue. I started learning GitHub via friends, youtube and a Ladies learning code event. @thomasgohard Did we ever have a session or slides like this for any of the CodeFests?

[mgifford]

I don't think there's been a Civic Tech presentation in Ottawa that we could leverage. Would be great to have a training for GitHub for non-technical users.

I know that @bendygirl has worked to educate folks in the USA Federal Gov on GitHub. Not sure what resources she used. Maybe there are some good quick videos out there.

I think mostly though what we need is more examples like @laurawesley - folks using GitHub for more than code in senior positions in government.

Also, the willingness to experiment and occasionally do something like close an issue that should be open... :)

[laurawesley]

Lol

Yes we did git101 @ codefest led by @jeresiv

Also, I almost just closed this issue. Damn mobile version 😋

[nschonni]

Related https://resources.github.com/webcasts/GitHub-writing-documentation-for-your-projects/?utm_source=services&utm_medium=site&utm_campaign=hgug-wbrs Might have some other workflow recommendations

[MaryBethBaker]

@mgifford @nschonni I took a intro to GitHub course via Ladies Learning to Code. Can someone let me know if this is a good French tutorial? It looks content wise complete and it has an English version: https://www.christopheducamp.com/2013/12/15/github-pour-nuls-partie-1/

English: http://readwrite.com/2013/09/30/understanding-github-a-journey-for-beginners-part-1/

//cc @RachelMuston

[gcharest]

Hi everyone, please note that we will be closing this issue which is more related to using GitHub rather than the whitepaper itself.

We do acknowledge that there is a steep learning curve in using GitHub/Git and we are investigating how we can improve participation and user experience.

As usual, you can reach us if you have questions or create specific issues for topics related to the whitepaper.