Re: Tools plea

Hi All,

I would tend to agree that we don’t want to create a process or use tools that create a lot of overhead. I think the lesson I personally took away from earlier iterations of our work is not to spend too much time up front worrying about formatting (in respec or other) before having a lot of “meat on the bones” of the document.  Also, I think it was really important for us to iterate on a single document by providing feedback and input into that document rather than creating alternate versions of the document (which I fear may have happened a bit on the wiki – largely because I think people did not feel as comfortable editing/updating work that others had done, so instead they created a separate example which led to a loss of traction).  Where Google docs had made it easier was that it was dead simple for me to comment on something and propose a modification right along side the rationale, without feeling like I was undoing or overriding someone else’s ideas entirely.  That being said, I think we could move to a different tool so long as 1) we don’t spend a lot of time on formatting until the doc is more “cooked” and the time spent is likely to be on content that is less apt to change and 2) that we have a good way to track comments and requests so that people can provide feedback and propose suggestions in a way that does not require them to destructively edit or create separate standalone content that others may also be reviewing at the same time.

Lastly, +1 to the defining a GIT workflow.  It occurs to me that Manu and team may have something like this based on some of the repository synch that happens with W3C version control, however I’m not sure that this is the case.  This would help define how to make suggestions and contribute content in a consistent way – especially for those less familiar with GIT.

Just my $0.02,

Pat

From: Adrian Hope-Bailie <adrian@hopebailie.com<mailto:adrian@hopebailie.com>>
Date: Wednesday, May 6, 2015 at 4:48 PM
To: Patrick Adler <patrick.adler@chi.frb.org<mailto:patrick.adler@chi.frb.org>>
Cc: Manu Sporny <msporny@digitalbazaar.com<mailto:msporny@digitalbazaar.com>>, "public-webpayments-ig@w3.org<mailto:public-webpayments-ig@w3.org>" <public-webpayments-ig@w3.org<mailto:public-webpayments-ig@w3.org>>
Subject: Re: Tools plea

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<mailto: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<mailto: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<mailto: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.






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.