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

Re: Tools plea

From: Adrian Hope-Bailie <adrian@hopebailie.com>
Date: Wed, 6 May 2015 23:48:08 +0200
Message-ID: <CA+eFz_KA_kn5KMT7XVj+n0zP82uYTakOo2qGqdi60nEMrW=xhA@mail.gmail.com>
To: "Adler, Patrick" <patrick.adler@chi.frb.org>
Cc: Manu Sporny <msporny@digitalbazaar.com>, "public-webpayments-ig@w3.org" <public-webpayments-ig@w3.org>
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.

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.
>>
>>
>>
>
Received on Wednesday, 6 May 2015 21:48:36 UTC

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