W3C home > Mailing lists > Public > public-webpayments-ig@w3.org > May 2015

Re: Tools plea

From: Ian Jacobs <ij@w3.org>
Date: Wed, 6 May 2015 22:39:54 -0500
Cc: "Adler, Patrick" <patrick.adler@chi.frb.org>, Manu Sporny <msporny@digitalbazaar.com>, "public-webpayments-ig@w3.org" <public-webpayments-ig@w3.org>
Message-Id: <E851EFEE-1939-41E5-9FB1-3C85F03BB6AE@w3.org>
To: Adrian Hope-Bailie <adrian@hopebailie.com>

> On May 6, 2015, at 4:48 PM, Adrian Hope-Bailie <adrian@hopebailie.com> wrote:
> p.s. It seems a bit sad that the best collaboration tool available on the Web to the people who are "building the Web" is a Wiki.

(We are working on getting a W3C instance of etherpad set up that we could use; I don’t have a time frame yet.)


> For those that want to edit ReSpec documents there is an EXCELLENT guide: https://www.w3.org/respec/
> All you need is a text editor and some very basic HTML knowledge (although if you follow the guide you'll probably not even need that).
> I have been experimenting with Microsoft's new free code editor Visual Studio Code which has Git integration built in, is dead simple and works very well: https://code.visualstudio.com/ (Runs on Windows, Mac and Linux)
> My last question is, do we have a Git flow defined anywhere?
> On 6 May 2015 at 21:50, Adrian Hope-Bailie <adrian@hopebailie.com> wrote:
> Hi all,
> I have just migrated the manifesto to the ReSpec format on GitHub:
> http://w3c.github.io/webpayments-ig/latest/manifesto/index.html
> It was a pretty time-consuming job so I'd suggest moving between formats is only done once. I see your motivations Pat, but I think the work of the editors will become very onerous if all of the feedback given into a Google Doc must be regularly pushed to the Wiki and then GitHub (or even just to GitHub).
> It's definitely unfortunate that Google Docs isn't working for a lot of folks, perhaps there is a similar, more user friendly tool than the wiki someone can suggest to try?
> Adrian
> On 6 May 2015 at 19:26, Adler, Patrick <patrick.adler@chi.frb.org> wrote:
> Hi All,
> Just wanted to add my $0.02 to the thread.  I¹m in a similar boat as Erik
> and Nick in that there are restrictions on a number of collaborative sites
> I am able to use due to the current (and necessary) security climate that
> has sadly become a way of life to protect the organizations we work for.
> That being said, and speaking as a heavy contributor of materials to the
> group, I do think the approach that Manu (+10 to Manu too :) ) outlines
> has been very effective in helping us to make progress quickly.  As an
> editor, I have had to work through some minor inconveniences (working on a
> standalone machine) to make edits to the early drafts on google docs, but
> have found the inline comments and edit suggestions worth the pain of
> doing so - at least for the earliest period of editing where there is a
> lot of discussion around certain topics.  To Nick¹s point (and I think it
> is a great one[+10 Nick]), we should be much more clear about that process
> and tools that are being used to edit the documents so that those that
> wanted to contribute know how and where the artifacts are and at which
> state they are in.  Also, I think it would be good to establish some kind
> of cadence to the editing process internally, so that if we are using
> multiple tools, there would be an easy way to know when to look for
> updates.
> Perhaps to add to Manu¹s suggestion below as a proposal, what would the
> group feel about the following?
> 1. Rough editors drafts and updates made daily to google docs (this is in
> a sense the bleeding edge of the document for those closest to it to
> structure thoughts on content and key material) - Likely this is most
> useful to core editors of the document
> This would provided the value of allowing editors to formulate content and
> thought process very efficiently at the expense of some barriers to direct
> access to this version from restrictive networks. Comments from all
> document locations are incorporated into this version (Google Docs, Wiki,
> Git/ReSpec)
> 2. On a minimum of a weekly basis, document is ³synched² to the wiki where
> they are accessible to the whole IG in an unrestrictive way, with a
> dedicated wiki page which contains feedback/content suggestions to be
> included in the next incremental update.  This would make it easy for
> editors to look for feedback, and since the whole document is regularly
> refreshed on a defined cadence, it helps people to know when they should
> look for new content without requiring the whole IG to respond to every
> minor incremental update (unless they wanted to)
> 3.  Once a draft has reached a fair level of stability, it could be
> migrated to Github and the Re-spec format and made visible as an editors
> draft or FPWD.  This prevents the editors from having to do a lot of extra
> formatting on material that may or may not make it into the final draft
> had we used only the respec format.
> Like Manu, I¹m open to working in a way that the group feels is most
> productive and inclusive and would welcome others thoughts on whether the
> outlined approach makes sense, or whether there are other options that we
> should pursue.
> Best regards,
> Pat
> On 5/6/15, 11:25 AM, "Manu Sporny" <msporny@digitalbazaar.com> wrote:
> >On 05/06/2015 08:28 AM, Telford-Reed, Nick wrote:
> >> Can we please standardise on where we are working?
> >
> >There is a method to the madness... :)
> >
> >In general, W3C groups tend to use the tools that make the people
> >contributing most effective.
> >
> >Google Docs are used for documents that are in the formative stages and
> >require a lot of collaborative editing and commenting. Documents live
> >here for a month or two and then move onto the Wiki or into Github.
> >
> >The Wiki is used for shorter content that requires less collaborative
> >editing and commenting. Content that we intend to publish lives here for
> >2-3 months while it is refined and then moves into Github.
> >
> >Github is used for documents that have stabilized a bit and will be
> >published via W3C. This is the long-term repository for the content
> >we're officially publishing as a group. ReSpec is the editing tool that
> >helps us format the content into the proper W3C publication format.
> >
> >So, the pipeline we have right now is:
> >
> >Google Docs -> Wiki -> Github
> >
> >Things move left to right as they reach certain levels of maturity.
> >
> >As for the firewall issues - yes, that sucks and if it's an issue and
> >you want to contribute to a Google Doc, we can move the doc into the
> >wiki (but we lose a good chunk of our collaborative ability in doing
> >so). The alternative being, use a non-firewalled network at work or at a
> >local coffee shop.
> >
> >I think everyone is open to finding something that works better for
> >contributors, so if you have a better idea, let us know and we'll try to
> >make it happen.
> >
> >-- manu
> >
> >--
> >Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
> >Founder/CEO - Digital Bazaar, Inc.
> >blog: High-Stakes Credentials and Web Login
> >http://manu.sporny.org/2014/identity-credentials/
> >
> This e-mail message, including attachments, is for the sole use of the intended recipient(s) and may contain confidential or proprietary information.  If you are not the intended recipient, immediately contact the sender by reply e-mail and destroy all copies of the original message.

Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
Tel:                       +1 718 260 9447
Received on Thursday, 7 May 2015 03:40:00 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:08:35 UTC