search

w3c / using-github

Obsolete repo; see https://github.com/w3c/modern-tooling and https://github.com/w3c/w3c.github.io
MIT License
3 stars 7 forks source link

What is the scope of this project? #11

Closed AFBarstow closed 8 years ago

AFBarstow commented 9 years ago

I would appreciate it if folks would please clarify the scope of this project.

Is its focus primarily identifying (and resolving) issues related to using Github at the consortium? I ask because the scope could also include actually creating and maintaining user-focused documentation such as: Best Practices, FAQs, cheat sheets, links to related resources, tips on migrating CVS/Hg repos to Github, etc.

I am aware of several documents and services about Github at W3C:

  1. Nick's Guide to Github
  2. Tantek's Github wiki
  3. Tobie's Using GitHub for Spec Work (@W3C)
  4. Dom's Github notification system

Perhaps this project could subsume some of the documents above (f.ex. 1. and 2.) (and it wouldn't surprise me if some groups have created similar resources/documents).

/Cc @npdoty @tantek @dontcallmedom @tobie

tantek commented 9 years ago

No idea what "github.com/w3c/using-github" is or what it's purpose is.

And it's not on w3.org.

could subsume some of the documents above (f.ex. 1. and 2.)

Nope. Regardless of what external site resources may be developed, it will always sense to keep an overview reference page at:

Feel free to add links to all the various github related efforts you (or anyone else) know of to W3C's Github wiki page. When you find "some groups have created similar resources/documents" add links to them to.

plehegar commented 9 years ago

On 04/11/2015 08:24 AM, Arthur Barstow wrote:

I would appreciate it if folks would please clarify the scope of this project.

Is its focus primarily identifying (and resolving) issues related to using Github at the consortium? I ask because the scope /could/ also include actually creating and maintaining user-focused documentation such as: Best Practices, FAQs, cheat sheets, links to related resources, tips on migrating CVS/Hg repos to Github, etc.

I am aware of several documents and services about Github at W3C:

  1. Nick's Guide to Github https://www.w3.org/wiki/Guide/GitHub
  2. Tantek's Github wiki https://www.w3.org/wiki/Github
  3. Tobie's Using GitHub for Spec Work (@W3C) http://tobie.github.io/specs-on-github/
  4. Dom's Github notification system https://github.com/dontcallmedom/github-notify-ml/

Perhaps this project could subsume some of the documents above (f.ex.

  1. and 2.) (and it wouldn't surprise me if some groups have created similar resources/documents).

/Cc @npdoty https://github.com/npdoty @tantek https://github.com/tantek @dontcallmedom https://github.com/dontcallmedom @tobie https://github.com/tobie

Speaking for my intent: the scope was to document was to use github for specifications: setup, wiki, issues, etc. Conventions for merge, commit, tagging, etc.

I find myself moving away from wikis nowadays: they don't allow us to track issues, propose and review pull requests, etc.

Philippe

darobin commented 9 years ago

And to address @AFBarstow's comment: yes, it ought to subsume the scattered existing documentation, in a manner that makes it easier to collaborate than a wiki.

tantek commented 9 years ago

Philippe wrote:

I find myself moving away from wikis nowadays: they don't allow us to track issues,

== Issues == section

propose and review pull requests, etc.

That's called a feature of having less process.

I.e. no need to propose, just edit.

No need for a "pull request" gatekeeper process, just trust people to edit the page, and fix/revert only when necessary.

Especially for non-normative documentation like this.

Philippe, all your "they don't allow us to ..." items are basically, "but I want more process to ..." - so I have to ask:

Why do you want more process? (more process = more inefficiency)

tantek commented 9 years ago

(nevermind the "not on a w3.org domain" issue that everyone seems to be ignoring)

npdoty commented 9 years ago

I would like us to consolidate documentation and suggestions for use of GitHub (for example, the wiki/Github links and the wiki/Guide/GitHub text) at some point. I would be happy to contribute either through editing one of those pages on the wiki, or via issues/pull requests in this repo on a markdown file that can be Jekyll-ized into nice HTML. (That could even be posted to w3.org if that machinery is developed.)

I would agree with Tantek that wherever documentation lives, existing wiki URLs should be maintained with pointers to current information.

plehegar commented 9 years ago

@tantek , I don't want more process. I want to get the work done. I simply don't believe that wikis are better tools to get the work done in this case. In my experience, we get more contributions through our github repos than we get through the various w3c wikis. The fact that you can either propose or edit through a github repo provides more flexibility for contributions imho.

tripu commented 9 years ago

I am not as familiar with the edition workflow as you people, but I suspect I agree with @plehegar here: GH is better than wikis, as a platform for collaboration in deliverables that are reasonably complex or long. Having more features doesn't necessarily mean having more overhead. And if there's a little more overhead with GH sometimes, I think that generally makes up for the limitations of a wiki.

The general concern (that @tantek hinted, if I understood him correctly) about working more and more outside w3.org, becoming too dependent on these third-party tools, and ensuring we continue to own the data in the future — I agree that is a very important one. The conversation is ongoing and there is discussion about taking appropriate measures.

liamquin commented 9 years ago

On Mon, 2015-04-13 at 22:19 -0700, tripu wrote:

The general concern (that @tantek hinted, if I understood him correctly) about working more and more outside w3.org, becoming too dependent on these third-party tools, and ensuring we continue to own the data in the future — I agree that is a very important one. The conversation is ongoing and there is discussion about taking appropriate measures.

I also have a concern that the programmer/technogeek community is driving a conversation that needs to be much more inclusive.

How accessible are all of the github tools, not only to people who are blind or vision impaired, mobility impared, have cognitive difficulties, but also to people who are technophobic?

It was a major struggle to get some editors using CVS, let alone git. I went to "gitter" and didn't see anything there saying "press this button to chat". Some learning is OK, but let's not rush headlong into the emacs collaborative gdb LISP mode for spec editing :-)

Liam

Liam Quin, XML Actvity lead, W3C

darobin commented 9 years ago

@tantek More interactions != more process. I often don't make changes in wikis because I am unsure that the changes I'm thinking of are done in the way that best matches what the people more familiar with the page have in mind. And also because I know that the very vast majority of people don't get notifications for wiki changes, and therefore can't act to tweak my change. Pull requests are a lot more social — it would possibly be interesting to see someone build a wiki on that principle. And don't get me started on wiki UIs or wikitext.

We have existing content under w3.org that's maintained on GitHub, it's very easily done. Management != publication.

Yes, this is centralised and that sucks. Yes, we should fix our technical ecosystem so that the best options aren't always centralised. But I don't think that we can get there without using the best tools at hand.

tripu commented 8 years ago

Closing, as this issue was not an issue, but a question and a call for clarification. A conversation ensued, and it has been stalled for seven months since.