You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jclouds.apache.org by Adrian Cole <ad...@gmail.com> on 2013/05/17 17:08:15 UTC
Documentation and what's next
Hi, team.
Since jclouds started, we've had many waves of doc efforts and approach. We
started with google wiki. It looked great and easy to update and control
access to. When we moved to GitHub we found access control absent which
led to Vijays hard work converting to markdown and hosting on github pages.
While some had patience to submit pull requests, our docs did rot. Becca
helped reface our website and spent a lot of effort to renovate select
documents and organized docs. She also removed the chance to completely
break the website due to accidentally breaking Jekyll. Meanwhile the
burden of fixing docs increased due to a combination of stricter
grammatical review and a perception that only Becca can approve things.
The commit log shows those tenacious enough can have content merged in a
couple weeks or so.
Meanwhile, docs are often hard to find or broken. When I nudge someone to
fix something, it is very rare when they open a pull request and rarer that
being merged within a week.
No one is at fault here, but I feel we've collectively boiled the frog. I
hope we can discuss this topic without anyone feeling attacked. This is
just reflection.
It should be easy to find, correct, and update docs. I work with many
projects and ours is by far the hardest to deal with. Something has to
give, and I'm apprehensive about fork lifting our old docs and process into
the ASF.
Personally, I really would love to use processes similar to what other
projects use for docs rather than being a snowflake. I desire less
friction, explaining, bottlenecks, special instructions and gotchas.
Do others feel this way? What options are on the table for doing
documentation in the ASF?
-A
Re: Documentation and what's next
Posted by Suresh Marru <sm...@apache.org>.
On May 17, 2013, at 11:42 AM, Andrew Phillips <ap...@qrmedia.com> wrote:
>> Sorry I should have found this answer by poking the git, I will take the lazy route by asking. Is the current markup still markdown?
>
> From what I know, yes. See e.g.
>
> https://github.com/jclouds/jclouds.github.com/tree/master/documentation/devguides
Great Thanks.
Then you may want to consider migrating to Apache CMS as one of the possibilities. More info - http://www.apache.org/dev/cms.html, http://www.apache.org/dev/cmsref.html.
Only gotcha is, this is svnpubsub based and there is no gitpubsub option.
Suresh
>
> ap
Re: Documentation and what's next
Posted by Andrew Phillips <ap...@qrmedia.com>.
> Sorry I should have found this answer by poking the git, I will take
> the lazy route by asking. Is the current markup still markdown?
From what I know, yes. See e.g.
https://github.com/jclouds/jclouds.github.com/tree/master/documentation/devguides
ap
Re: Documentation and what's next
Posted by Suresh Marru <sm...@apache.org>.
Hi Adrian,
Sorry I should have found this answer by poking the git, I will take the lazy route by asking. Is the current markup still markdown?
Suresh
On May 17, 2013, at 11:08 AM, Adrian Cole <ad...@gmail.com> wrote:
> Hi, team.
>
> Since jclouds started, we've had many waves of doc efforts and approach. We
> started with google wiki. It looked great and easy to update and control
> access to. When we moved to GitHub we found access control absent which
> led to Vijays hard work converting to markdown and hosting on github pages.
> While some had patience to submit pull requests, our docs did rot. Becca
> helped reface our website and spent a lot of effort to renovate select
> documents and organized docs. She also removed the chance to completely
> break the website due to accidentally breaking Jekyll. Meanwhile the
> burden of fixing docs increased due to a combination of stricter
> grammatical review and a perception that only Becca can approve things.
> The commit log shows those tenacious enough can have content merged in a
> couple weeks or so.
>
> Meanwhile, docs are often hard to find or broken. When I nudge someone to
> fix something, it is very rare when they open a pull request and rarer that
> being merged within a week.
>
> No one is at fault here, but I feel we've collectively boiled the frog. I
> hope we can discuss this topic without anyone feeling attacked. This is
> just reflection.
>
> It should be easy to find, correct, and update docs. I work with many
> projects and ours is by far the hardest to deal with. Something has to
> give, and I'm apprehensive about fork lifting our old docs and process into
> the ASF.
>
> Personally, I really would love to use processes similar to what other
> projects use for docs rather than being a snowflake. I desire less
> friction, explaining, bottlenecks, special instructions and gotchas.
>
> Do others feel this way? What options are on the table for doing
> documentation in the ASF?
>
> -A
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Here's some projects I also help with, and what they do for docs. I could
list more if needed.
Apache Whirr: doc updates are often pushed directly without jira, or
updated via wiki
://cwiki.apache.org/confluence/display/WHIRR
https://github.com/apache/whirr/tree/trunk/src/site
Netflix: doc updates are usually pushed directly without review, sometimes
via pull request. wikis are often used.
Decentralized doc responsibility; Org manages links to repositories
http://netflix.github.io https://github.com/Netflix/netflix.github.com
Ex. Denominator:
wiki + README files
https://github.com/Netflix/denominator
denominator-specific website linked to by org-specific github pages
site:
http://netflix.github.io
https://github.com/Netflix/netflix.github.com
Square: doc updates are usually pushed directly without review, sometimes
via pull request. wikis are not used.
Decentralized doc responsibility; Org manages links to repositories
http://square.github.io/ https://github.com/square/square.github.io
Ex. Dagger:
static html managed by git or pull request
https://github.com/square/dagger/blob/master/website
website published on gh-pages branch and includes generated javadocs
https://github.com/square/dagger/tree/gh-pages
On Fri, May 17, 2013 at 8:29 AM, Andrew Phillips <ap...@qrmedia.com>wrote:
> Personally, I really would love to use processes similar to what other
>> projects use for docs rather than being a snowflake.
>>
>
> Do you have some references to the processes the other projects use, as a
> guide to get some ideas?
>
> Thanks!
>
> ap
>
Re: Documentation and what's next
Posted by Andrew Phillips <ap...@qrmedia.com>.
> Personally, I really would love to use processes similar to what other
> projects use for docs rather than being a snowflake.
Do you have some references to the processes the other projects use,
as a guide to get some ideas?
Thanks!
ap
Re: Documentation and what's next
Posted by Ioannis Canellos <io...@gmail.com>.
> We all want good docs, and we can't let best be the enemy of that.
>
Says all in a single sentence! +1
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
I appreciate your note, Matt. Glad to know it was unintentional and
we have to take stuff as a grain of salt.
Best,
-A
On Sun, May 19, 2013 at 8:56 PM, Matt Stephenson <ma...@apache.org> wrote:
> See, that's kinda what I'm worried about. If I'm the problem that's
> causing you to want to rage quit, then just let me know before it gets
> there and lets make sure I'm on the same page as you. I don't want to be
> the problem, that's certainly not my intent, I'm just kinda dense sometimes
> about that.
>
> I think we've spoken before that I like to dig deep on issues until I
> really have a strong shared understanding. I don't want that to piss
> people off. I'm sure there are plenty that it has.
>
> I probably will get deep under someone's skin along these exact lines in
> the coming weeks/months. Feel free to ping me via any of the vast array of
> contact options many of you have for me personally if you need to. I'm
> actually not as thorny as I seem sometimes.
>
>
> On Sun, May 19, 2013 at 8:47 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> If there was anything personal, it would have been in your benefit.
>> My saying you're responsible is that you didn't let go in context of
>> the discussion thread now approaching 60 messages. Instead of
>> adopting the community decision, you relentlessly pummeled the list.
>> It isn't personal, but you are involved.
>>
>> On Sun, May 19, 2013 at 8:36 PM, Matt Stephenson <ma...@apache.org>
>> wrote:
>> > Dude, if there is a personal thing going on, lets hash it out off-list,
>> I'm
>> > happy to make time to meet up. I'd rather keep the emotions out of the
>> > equation on here. I don't think anyone wants to take control, and all of
>> > us want to increase the bus factor.
>> >
>> >
>> > On Sun, May 19, 2013 at 8:31 PM, Adrian Cole <adrian.f.cole@gmail.com
>> >wrote:
>> >
>> >> Here's my "rage quit" tweet:
>> >>
>> >> I don't want to write a "why I left #jclouds" blog, but man I didn't
>> >> sign up for pointless fights wrt control. I hope things get better
>> >> fast
>> >>
>> >> Concerns about censoring my tweets are especially ironic in a thread
>> >> where I'm fighting for freedom for us to write docs without policing
>> >> each-other and uphold legitimate votes. There's nothing about apache
>> >> or any other organization that will stop me from voicing my positive
>> >> and negative opinions of my experiences. Congratulations for being
>> >> personally responsible for this one.
>> >>
>> >> -A
>> >>
>> >>
>> >> On Sun, May 19, 2013 at 8:03 PM, Matt Stephenson <ma...@apache.org>
>> >> wrote:
>> >> > I am not digging the twitter traffic about this thread after several
>> >> people
>> >> > were merely confused about what we're trying to do with docs. I've
>> >> finally
>> >> > gone through the last few weeks of emails, and these types of changes
>> can
>> >> > blindside some people unless enough discussion happened. I'm really
>> >> > disappointed in how many times individuals were called out by name,
>> and
>> >> > certain points in the thread history was publicly tweeted out.
>> >> >
>> >> > Adrian, no one wants you to rage quit from jclouds, but sometimes we
>> >> need a
>> >> > shared understanding. Three people on this thread didn't understand
>> that
>> >> > you were talking just about the wiki. Several people thought you were
>> >> > talking about C-T-R on the current setup for documentation. I'm
>> sorry if
>> >> > I'm being too dense for you, but I've been trying to keep up with all
>> the
>> >> > discussions here.
>> >> >
>> >> > I'm curious to see how the other threads pan out. We have had no one
>> >> > really lay out what we want users of jclouds to actually see. If
>> someone
>> >> > has the cycles to do that, it probably would bring more form to these
>> >> types
>> >> > of discussion.
>> >> >
>> >> > Are we setting a standard that in order to voice your opinion or try
>> to
>> >> get
>> >> > further clarification, you need to be able to deal with all the
>> twitter
>> >> > publicity you might end up with? Sounds like bullying to me.
>> >> >
>> >> >
>> >> > On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
>> >> >
>> >> >> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <
>> adrian.f.cole@gmail.com>
>> >> >> wrote:
>> >> >> > Perhaps we are in violent agreement, David. If so, then we see
>> R-T-C
>> >> >> > applying to "code" and change committed as being by committers.
>> If
>> >> we
>> >> >> are
>> >> >> > seeing eye to eye wed would understand that documentation, while an
>> >> >> > important asset, is not usually under the same formalities as code.
>> >> If
>> >> >> it
>> >> >> > were, apache run wikis and indeed most doc updates couldn't
>> operate as
>> >> >> they
>> >> >> > do. If we agree to this than R-T-C is a policy that was made for
>> code
>> >> >> and
>> >> >> > rarely applies to documentation.
>> >> >> >
>> >> >> > As your note seems to imply an equal replacement of terms like
>> >> committer
>> >> >> or
>> >> >> > developer with the word contributor, and documentation with code, I
>> >> think
>> >> >> > we don't violently agree, though it is possible we are talking at
>> each
>> >> >> > other.
>> >> >> >
>> >> >> > From a process perspective, I believe documentation can operate as
>> >> >> > code. I'm not dismissing this potential and I'm aware of tools to
>> >> >> > facilitate that. I believe operating docs as code is a choice, but
>> >> not
>> >> >> the
>> >> >> > only choice. It is an optimization.
>> >> >> >
>> >> >> > Do you understand why one might call a vote on a process for
>> >> >> documentation
>> >> >> > and contributors, if we believed that C-T-R or R-T-C was focused on
>> >> code
>> >> >> > and committers?
>> >> >> >
>> >> >> > I know it is possible to pull technicalities and use rules to say
>> >> >> whatever
>> >> >> > we want them to. I'm not trying to get into a technicality fight
>> >> here.
>> >> >> I
>> >> >> > want to be able to operate in this project and facilitate docs like
>> >> other
>> >> >> > projects. If agreeing with you allows this conversation to stop
>> and
>> >> >> > doesn't reverse the intent of the vote then. I agree.
>> >> >> >
>> >> >>
>> >> >>
>> >> >> Doh!! now I see the difference; and why I am so confused.
>> >> >> Yes, I was equating code and docs - and assuming they were identical
>> >> >> for the purposes of this discussion - which clearly is not always the
>> >> >> case.
>> >> >> (Sadly you are seeing some of my CloudStack preconcieved notions
>> >> >> coming through. - we maintain our formal docs as pseudo-code (DocBook
>> >> >> XML) we build and publish it with pseudo-build tools (Publican) and
>> >> >> most importantly, it is a part of the source code in our releases.)
>> So
>> >> >> the caveat is that anything that the project _releases_ probably
>> >> >> deserves the same treatment as code. If however that's not part of
>> >> >> your release. Publication isn't a release - and as you point out, we
>> >> >> have copious wiki examples, official blog entries, and others that
>> >> >> aren't part of a code-like release.
>> >> >>
>> >> >> Apologies for not catching on earlier, thanks for illuminating me.
>> >> >>
>> >> >> --David
>> >> >>
>> >>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
See, that's kinda what I'm worried about. If I'm the problem that's
causing you to want to rage quit, then just let me know before it gets
there and lets make sure I'm on the same page as you. I don't want to be
the problem, that's certainly not my intent, I'm just kinda dense sometimes
about that.
I think we've spoken before that I like to dig deep on issues until I
really have a strong shared understanding. I don't want that to piss
people off. I'm sure there are plenty that it has.
I probably will get deep under someone's skin along these exact lines in
the coming weeks/months. Feel free to ping me via any of the vast array of
contact options many of you have for me personally if you need to. I'm
actually not as thorny as I seem sometimes.
On Sun, May 19, 2013 at 8:47 PM, Adrian Cole <ad...@gmail.com>wrote:
> If there was anything personal, it would have been in your benefit.
> My saying you're responsible is that you didn't let go in context of
> the discussion thread now approaching 60 messages. Instead of
> adopting the community decision, you relentlessly pummeled the list.
> It isn't personal, but you are involved.
>
> On Sun, May 19, 2013 at 8:36 PM, Matt Stephenson <ma...@apache.org>
> wrote:
> > Dude, if there is a personal thing going on, lets hash it out off-list,
> I'm
> > happy to make time to meet up. I'd rather keep the emotions out of the
> > equation on here. I don't think anyone wants to take control, and all of
> > us want to increase the bus factor.
> >
> >
> > On Sun, May 19, 2013 at 8:31 PM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
> >
> >> Here's my "rage quit" tweet:
> >>
> >> I don't want to write a "why I left #jclouds" blog, but man I didn't
> >> sign up for pointless fights wrt control. I hope things get better
> >> fast
> >>
> >> Concerns about censoring my tweets are especially ironic in a thread
> >> where I'm fighting for freedom for us to write docs without policing
> >> each-other and uphold legitimate votes. There's nothing about apache
> >> or any other organization that will stop me from voicing my positive
> >> and negative opinions of my experiences. Congratulations for being
> >> personally responsible for this one.
> >>
> >> -A
> >>
> >>
> >> On Sun, May 19, 2013 at 8:03 PM, Matt Stephenson <ma...@apache.org>
> >> wrote:
> >> > I am not digging the twitter traffic about this thread after several
> >> people
> >> > were merely confused about what we're trying to do with docs. I've
> >> finally
> >> > gone through the last few weeks of emails, and these types of changes
> can
> >> > blindside some people unless enough discussion happened. I'm really
> >> > disappointed in how many times individuals were called out by name,
> and
> >> > certain points in the thread history was publicly tweeted out.
> >> >
> >> > Adrian, no one wants you to rage quit from jclouds, but sometimes we
> >> need a
> >> > shared understanding. Three people on this thread didn't understand
> that
> >> > you were talking just about the wiki. Several people thought you were
> >> > talking about C-T-R on the current setup for documentation. I'm
> sorry if
> >> > I'm being too dense for you, but I've been trying to keep up with all
> the
> >> > discussions here.
> >> >
> >> > I'm curious to see how the other threads pan out. We have had no one
> >> > really lay out what we want users of jclouds to actually see. If
> someone
> >> > has the cycles to do that, it probably would bring more form to these
> >> types
> >> > of discussion.
> >> >
> >> > Are we setting a standard that in order to voice your opinion or try
> to
> >> get
> >> > further clarification, you need to be able to deal with all the
> twitter
> >> > publicity you might end up with? Sounds like bullying to me.
> >> >
> >> >
> >> > On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
> >> >
> >> >> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <
> adrian.f.cole@gmail.com>
> >> >> wrote:
> >> >> > Perhaps we are in violent agreement, David. If so, then we see
> R-T-C
> >> >> > applying to "code" and change committed as being by committers.
> If
> >> we
> >> >> are
> >> >> > seeing eye to eye wed would understand that documentation, while an
> >> >> > important asset, is not usually under the same formalities as code.
> >> If
> >> >> it
> >> >> > were, apache run wikis and indeed most doc updates couldn't
> operate as
> >> >> they
> >> >> > do. If we agree to this than R-T-C is a policy that was made for
> code
> >> >> and
> >> >> > rarely applies to documentation.
> >> >> >
> >> >> > As your note seems to imply an equal replacement of terms like
> >> committer
> >> >> or
> >> >> > developer with the word contributor, and documentation with code, I
> >> think
> >> >> > we don't violently agree, though it is possible we are talking at
> each
> >> >> > other.
> >> >> >
> >> >> > From a process perspective, I believe documentation can operate as
> >> >> > code. I'm not dismissing this potential and I'm aware of tools to
> >> >> > facilitate that. I believe operating docs as code is a choice, but
> >> not
> >> >> the
> >> >> > only choice. It is an optimization.
> >> >> >
> >> >> > Do you understand why one might call a vote on a process for
> >> >> documentation
> >> >> > and contributors, if we believed that C-T-R or R-T-C was focused on
> >> code
> >> >> > and committers?
> >> >> >
> >> >> > I know it is possible to pull technicalities and use rules to say
> >> >> whatever
> >> >> > we want them to. I'm not trying to get into a technicality fight
> >> here.
> >> >> I
> >> >> > want to be able to operate in this project and facilitate docs like
> >> other
> >> >> > projects. If agreeing with you allows this conversation to stop
> and
> >> >> > doesn't reverse the intent of the vote then. I agree.
> >> >> >
> >> >>
> >> >>
> >> >> Doh!! now I see the difference; and why I am so confused.
> >> >> Yes, I was equating code and docs - and assuming they were identical
> >> >> for the purposes of this discussion - which clearly is not always the
> >> >> case.
> >> >> (Sadly you are seeing some of my CloudStack preconcieved notions
> >> >> coming through. - we maintain our formal docs as pseudo-code (DocBook
> >> >> XML) we build and publish it with pseudo-build tools (Publican) and
> >> >> most importantly, it is a part of the source code in our releases.)
> So
> >> >> the caveat is that anything that the project _releases_ probably
> >> >> deserves the same treatment as code. If however that's not part of
> >> >> your release. Publication isn't a release - and as you point out, we
> >> >> have copious wiki examples, official blog entries, and others that
> >> >> aren't part of a code-like release.
> >> >>
> >> >> Apologies for not catching on earlier, thanks for illuminating me.
> >> >>
> >> >> --David
> >> >>
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
If there was anything personal, it would have been in your benefit.
My saying you're responsible is that you didn't let go in context of
the discussion thread now approaching 60 messages. Instead of
adopting the community decision, you relentlessly pummeled the list.
It isn't personal, but you are involved.
On Sun, May 19, 2013 at 8:36 PM, Matt Stephenson <ma...@apache.org> wrote:
> Dude, if there is a personal thing going on, lets hash it out off-list, I'm
> happy to make time to meet up. I'd rather keep the emotions out of the
> equation on here. I don't think anyone wants to take control, and all of
> us want to increase the bus factor.
>
>
> On Sun, May 19, 2013 at 8:31 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> Here's my "rage quit" tweet:
>>
>> I don't want to write a "why I left #jclouds" blog, but man I didn't
>> sign up for pointless fights wrt control. I hope things get better
>> fast
>>
>> Concerns about censoring my tweets are especially ironic in a thread
>> where I'm fighting for freedom for us to write docs without policing
>> each-other and uphold legitimate votes. There's nothing about apache
>> or any other organization that will stop me from voicing my positive
>> and negative opinions of my experiences. Congratulations for being
>> personally responsible for this one.
>>
>> -A
>>
>>
>> On Sun, May 19, 2013 at 8:03 PM, Matt Stephenson <ma...@apache.org>
>> wrote:
>> > I am not digging the twitter traffic about this thread after several
>> people
>> > were merely confused about what we're trying to do with docs. I've
>> finally
>> > gone through the last few weeks of emails, and these types of changes can
>> > blindside some people unless enough discussion happened. I'm really
>> > disappointed in how many times individuals were called out by name, and
>> > certain points in the thread history was publicly tweeted out.
>> >
>> > Adrian, no one wants you to rage quit from jclouds, but sometimes we
>> need a
>> > shared understanding. Three people on this thread didn't understand that
>> > you were talking just about the wiki. Several people thought you were
>> > talking about C-T-R on the current setup for documentation. I'm sorry if
>> > I'm being too dense for you, but I've been trying to keep up with all the
>> > discussions here.
>> >
>> > I'm curious to see how the other threads pan out. We have had no one
>> > really lay out what we want users of jclouds to actually see. If someone
>> > has the cycles to do that, it probably would bring more form to these
>> types
>> > of discussion.
>> >
>> > Are we setting a standard that in order to voice your opinion or try to
>> get
>> > further clarification, you need to be able to deal with all the twitter
>> > publicity you might end up with? Sounds like bullying to me.
>> >
>> >
>> > On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
>> >
>> >> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <ad...@gmail.com>
>> >> wrote:
>> >> > Perhaps we are in violent agreement, David. If so, then we see R-T-C
>> >> > applying to "code" and change committed as being by committers. If
>> we
>> >> are
>> >> > seeing eye to eye wed would understand that documentation, while an
>> >> > important asset, is not usually under the same formalities as code.
>> If
>> >> it
>> >> > were, apache run wikis and indeed most doc updates couldn't operate as
>> >> they
>> >> > do. If we agree to this than R-T-C is a policy that was made for code
>> >> and
>> >> > rarely applies to documentation.
>> >> >
>> >> > As your note seems to imply an equal replacement of terms like
>> committer
>> >> or
>> >> > developer with the word contributor, and documentation with code, I
>> think
>> >> > we don't violently agree, though it is possible we are talking at each
>> >> > other.
>> >> >
>> >> > From a process perspective, I believe documentation can operate as
>> >> > code. I'm not dismissing this potential and I'm aware of tools to
>> >> > facilitate that. I believe operating docs as code is a choice, but
>> not
>> >> the
>> >> > only choice. It is an optimization.
>> >> >
>> >> > Do you understand why one might call a vote on a process for
>> >> documentation
>> >> > and contributors, if we believed that C-T-R or R-T-C was focused on
>> code
>> >> > and committers?
>> >> >
>> >> > I know it is possible to pull technicalities and use rules to say
>> >> whatever
>> >> > we want them to. I'm not trying to get into a technicality fight
>> here.
>> >> I
>> >> > want to be able to operate in this project and facilitate docs like
>> other
>> >> > projects. If agreeing with you allows this conversation to stop and
>> >> > doesn't reverse the intent of the vote then. I agree.
>> >> >
>> >>
>> >>
>> >> Doh!! now I see the difference; and why I am so confused.
>> >> Yes, I was equating code and docs - and assuming they were identical
>> >> for the purposes of this discussion - which clearly is not always the
>> >> case.
>> >> (Sadly you are seeing some of my CloudStack preconcieved notions
>> >> coming through. - we maintain our formal docs as pseudo-code (DocBook
>> >> XML) we build and publish it with pseudo-build tools (Publican) and
>> >> most importantly, it is a part of the source code in our releases.) So
>> >> the caveat is that anything that the project _releases_ probably
>> >> deserves the same treatment as code. If however that's not part of
>> >> your release. Publication isn't a release - and as you point out, we
>> >> have copious wiki examples, official blog entries, and others that
>> >> aren't part of a code-like release.
>> >>
>> >> Apologies for not catching on earlier, thanks for illuminating me.
>> >>
>> >> --David
>> >>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
Dude, if there is a personal thing going on, lets hash it out off-list, I'm
happy to make time to meet up. I'd rather keep the emotions out of the
equation on here. I don't think anyone wants to take control, and all of
us want to increase the bus factor.
On Sun, May 19, 2013 at 8:31 PM, Adrian Cole <ad...@gmail.com>wrote:
> Here's my "rage quit" tweet:
>
> I don't want to write a "why I left #jclouds" blog, but man I didn't
> sign up for pointless fights wrt control. I hope things get better
> fast
>
> Concerns about censoring my tweets are especially ironic in a thread
> where I'm fighting for freedom for us to write docs without policing
> each-other and uphold legitimate votes. There's nothing about apache
> or any other organization that will stop me from voicing my positive
> and negative opinions of my experiences. Congratulations for being
> personally responsible for this one.
>
> -A
>
>
> On Sun, May 19, 2013 at 8:03 PM, Matt Stephenson <ma...@apache.org>
> wrote:
> > I am not digging the twitter traffic about this thread after several
> people
> > were merely confused about what we're trying to do with docs. I've
> finally
> > gone through the last few weeks of emails, and these types of changes can
> > blindside some people unless enough discussion happened. I'm really
> > disappointed in how many times individuals were called out by name, and
> > certain points in the thread history was publicly tweeted out.
> >
> > Adrian, no one wants you to rage quit from jclouds, but sometimes we
> need a
> > shared understanding. Three people on this thread didn't understand that
> > you were talking just about the wiki. Several people thought you were
> > talking about C-T-R on the current setup for documentation. I'm sorry if
> > I'm being too dense for you, but I've been trying to keep up with all the
> > discussions here.
> >
> > I'm curious to see how the other threads pan out. We have had no one
> > really lay out what we want users of jclouds to actually see. If someone
> > has the cycles to do that, it probably would bring more form to these
> types
> > of discussion.
> >
> > Are we setting a standard that in order to voice your opinion or try to
> get
> > further clarification, you need to be able to deal with all the twitter
> > publicity you might end up with? Sounds like bullying to me.
> >
> >
> > On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
> >
> >> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <ad...@gmail.com>
> >> wrote:
> >> > Perhaps we are in violent agreement, David. If so, then we see R-T-C
> >> > applying to "code" and change committed as being by committers. If
> we
> >> are
> >> > seeing eye to eye wed would understand that documentation, while an
> >> > important asset, is not usually under the same formalities as code.
> If
> >> it
> >> > were, apache run wikis and indeed most doc updates couldn't operate as
> >> they
> >> > do. If we agree to this than R-T-C is a policy that was made for code
> >> and
> >> > rarely applies to documentation.
> >> >
> >> > As your note seems to imply an equal replacement of terms like
> committer
> >> or
> >> > developer with the word contributor, and documentation with code, I
> think
> >> > we don't violently agree, though it is possible we are talking at each
> >> > other.
> >> >
> >> > From a process perspective, I believe documentation can operate as
> >> > code. I'm not dismissing this potential and I'm aware of tools to
> >> > facilitate that. I believe operating docs as code is a choice, but
> not
> >> the
> >> > only choice. It is an optimization.
> >> >
> >> > Do you understand why one might call a vote on a process for
> >> documentation
> >> > and contributors, if we believed that C-T-R or R-T-C was focused on
> code
> >> > and committers?
> >> >
> >> > I know it is possible to pull technicalities and use rules to say
> >> whatever
> >> > we want them to. I'm not trying to get into a technicality fight
> here.
> >> I
> >> > want to be able to operate in this project and facilitate docs like
> other
> >> > projects. If agreeing with you allows this conversation to stop and
> >> > doesn't reverse the intent of the vote then. I agree.
> >> >
> >>
> >>
> >> Doh!! now I see the difference; and why I am so confused.
> >> Yes, I was equating code and docs - and assuming they were identical
> >> for the purposes of this discussion - which clearly is not always the
> >> case.
> >> (Sadly you are seeing some of my CloudStack preconcieved notions
> >> coming through. - we maintain our formal docs as pseudo-code (DocBook
> >> XML) we build and publish it with pseudo-build tools (Publican) and
> >> most importantly, it is a part of the source code in our releases.) So
> >> the caveat is that anything that the project _releases_ probably
> >> deserves the same treatment as code. If however that's not part of
> >> your release. Publication isn't a release - and as you point out, we
> >> have copious wiki examples, official blog entries, and others that
> >> aren't part of a code-like release.
> >>
> >> Apologies for not catching on earlier, thanks for illuminating me.
> >>
> >> --David
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Here's my "rage quit" tweet:
I don't want to write a "why I left #jclouds" blog, but man I didn't
sign up for pointless fights wrt control. I hope things get better
fast
Concerns about censoring my tweets are especially ironic in a thread
where I'm fighting for freedom for us to write docs without policing
each-other and uphold legitimate votes. There's nothing about apache
or any other organization that will stop me from voicing my positive
and negative opinions of my experiences. Congratulations for being
personally responsible for this one.
-A
On Sun, May 19, 2013 at 8:03 PM, Matt Stephenson <ma...@apache.org> wrote:
> I am not digging the twitter traffic about this thread after several people
> were merely confused about what we're trying to do with docs. I've finally
> gone through the last few weeks of emails, and these types of changes can
> blindside some people unless enough discussion happened. I'm really
> disappointed in how many times individuals were called out by name, and
> certain points in the thread history was publicly tweeted out.
>
> Adrian, no one wants you to rage quit from jclouds, but sometimes we need a
> shared understanding. Three people on this thread didn't understand that
> you were talking just about the wiki. Several people thought you were
> talking about C-T-R on the current setup for documentation. I'm sorry if
> I'm being too dense for you, but I've been trying to keep up with all the
> discussions here.
>
> I'm curious to see how the other threads pan out. We have had no one
> really lay out what we want users of jclouds to actually see. If someone
> has the cycles to do that, it probably would bring more form to these types
> of discussion.
>
> Are we setting a standard that in order to voice your opinion or try to get
> further clarification, you need to be able to deal with all the twitter
> publicity you might end up with? Sounds like bullying to me.
>
>
> On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
>
>> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <ad...@gmail.com>
>> wrote:
>> > Perhaps we are in violent agreement, David. If so, then we see R-T-C
>> > applying to "code" and change committed as being by committers. If we
>> are
>> > seeing eye to eye wed would understand that documentation, while an
>> > important asset, is not usually under the same formalities as code. If
>> it
>> > were, apache run wikis and indeed most doc updates couldn't operate as
>> they
>> > do. If we agree to this than R-T-C is a policy that was made for code
>> and
>> > rarely applies to documentation.
>> >
>> > As your note seems to imply an equal replacement of terms like committer
>> or
>> > developer with the word contributor, and documentation with code, I think
>> > we don't violently agree, though it is possible we are talking at each
>> > other.
>> >
>> > From a process perspective, I believe documentation can operate as
>> > code. I'm not dismissing this potential and I'm aware of tools to
>> > facilitate that. I believe operating docs as code is a choice, but not
>> the
>> > only choice. It is an optimization.
>> >
>> > Do you understand why one might call a vote on a process for
>> documentation
>> > and contributors, if we believed that C-T-R or R-T-C was focused on code
>> > and committers?
>> >
>> > I know it is possible to pull technicalities and use rules to say
>> whatever
>> > we want them to. I'm not trying to get into a technicality fight here.
>> I
>> > want to be able to operate in this project and facilitate docs like other
>> > projects. If agreeing with you allows this conversation to stop and
>> > doesn't reverse the intent of the vote then. I agree.
>> >
>>
>>
>> Doh!! now I see the difference; and why I am so confused.
>> Yes, I was equating code and docs - and assuming they were identical
>> for the purposes of this discussion - which clearly is not always the
>> case.
>> (Sadly you are seeing some of my CloudStack preconcieved notions
>> coming through. - we maintain our formal docs as pseudo-code (DocBook
>> XML) we build and publish it with pseudo-build tools (Publican) and
>> most importantly, it is a part of the source code in our releases.) So
>> the caveat is that anything that the project _releases_ probably
>> deserves the same treatment as code. If however that's not part of
>> your release. Publication isn't a release - and as you point out, we
>> have copious wiki examples, official blog entries, and others that
>> aren't part of a code-like release.
>>
>> Apologies for not catching on earlier, thanks for illuminating me.
>>
>> --David
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
I am not digging the twitter traffic about this thread after several people
were merely confused about what we're trying to do with docs. I've finally
gone through the last few weeks of emails, and these types of changes can
blindside some people unless enough discussion happened. I'm really
disappointed in how many times individuals were called out by name, and
certain points in the thread history was publicly tweeted out.
Adrian, no one wants you to rage quit from jclouds, but sometimes we need a
shared understanding. Three people on this thread didn't understand that
you were talking just about the wiki. Several people thought you were
talking about C-T-R on the current setup for documentation. I'm sorry if
I'm being too dense for you, but I've been trying to keep up with all the
discussions here.
I'm curious to see how the other threads pan out. We have had no one
really lay out what we want users of jclouds to actually see. If someone
has the cycles to do that, it probably would bring more form to these types
of discussion.
Are we setting a standard that in order to voice your opinion or try to get
further clarification, you need to be able to deal with all the twitter
publicity you might end up with? Sounds like bullying to me.
On Sun, May 19, 2013 at 6:23 PM, David Nalley <da...@gnsa.us> wrote:
> On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <ad...@gmail.com>
> wrote:
> > Perhaps we are in violent agreement, David. If so, then we see R-T-C
> > applying to "code" and change committed as being by committers. If we
> are
> > seeing eye to eye wed would understand that documentation, while an
> > important asset, is not usually under the same formalities as code. If
> it
> > were, apache run wikis and indeed most doc updates couldn't operate as
> they
> > do. If we agree to this than R-T-C is a policy that was made for code
> and
> > rarely applies to documentation.
> >
> > As your note seems to imply an equal replacement of terms like committer
> or
> > developer with the word contributor, and documentation with code, I think
> > we don't violently agree, though it is possible we are talking at each
> > other.
> >
> > From a process perspective, I believe documentation can operate as
> > code. I'm not dismissing this potential and I'm aware of tools to
> > facilitate that. I believe operating docs as code is a choice, but not
> the
> > only choice. It is an optimization.
> >
> > Do you understand why one might call a vote on a process for
> documentation
> > and contributors, if we believed that C-T-R or R-T-C was focused on code
> > and committers?
> >
> > I know it is possible to pull technicalities and use rules to say
> whatever
> > we want them to. I'm not trying to get into a technicality fight here.
> I
> > want to be able to operate in this project and facilitate docs like other
> > projects. If agreeing with you allows this conversation to stop and
> > doesn't reverse the intent of the vote then. I agree.
> >
>
>
> Doh!! now I see the difference; and why I am so confused.
> Yes, I was equating code and docs - and assuming they were identical
> for the purposes of this discussion - which clearly is not always the
> case.
> (Sadly you are seeing some of my CloudStack preconcieved notions
> coming through. - we maintain our formal docs as pseudo-code (DocBook
> XML) we build and publish it with pseudo-build tools (Publican) and
> most importantly, it is a part of the source code in our releases.) So
> the caveat is that anything that the project _releases_ probably
> deserves the same treatment as code. If however that's not part of
> your release. Publication isn't a release - and as you point out, we
> have copious wiki examples, official blog entries, and others that
> aren't part of a code-like release.
>
> Apologies for not catching on earlier, thanks for illuminating me.
>
> --David
>
Re: Documentation and what's next
Posted by David Nalley <da...@gnsa.us>.
On Sun, May 19, 2013 at 6:16 PM, Adrian Cole <ad...@gmail.com> wrote:
> Perhaps we are in violent agreement, David. If so, then we see R-T-C
> applying to "code" and change committed as being by committers. If we are
> seeing eye to eye wed would understand that documentation, while an
> important asset, is not usually under the same formalities as code. If it
> were, apache run wikis and indeed most doc updates couldn't operate as they
> do. If we agree to this than R-T-C is a policy that was made for code and
> rarely applies to documentation.
>
> As your note seems to imply an equal replacement of terms like committer or
> developer with the word contributor, and documentation with code, I think
> we don't violently agree, though it is possible we are talking at each
> other.
>
> From a process perspective, I believe documentation can operate as
> code. I'm not dismissing this potential and I'm aware of tools to
> facilitate that. I believe operating docs as code is a choice, but not the
> only choice. It is an optimization.
>
> Do you understand why one might call a vote on a process for documentation
> and contributors, if we believed that C-T-R or R-T-C was focused on code
> and committers?
>
> I know it is possible to pull technicalities and use rules to say whatever
> we want them to. I'm not trying to get into a technicality fight here. I
> want to be able to operate in this project and facilitate docs like other
> projects. If agreeing with you allows this conversation to stop and
> doesn't reverse the intent of the vote then. I agree.
>
Doh!! now I see the difference; and why I am so confused.
Yes, I was equating code and docs - and assuming they were identical
for the purposes of this discussion - which clearly is not always the
case.
(Sadly you are seeing some of my CloudStack preconcieved notions
coming through. - we maintain our formal docs as pseudo-code (DocBook
XML) we build and publish it with pseudo-build tools (Publican) and
most importantly, it is a part of the source code in our releases.) So
the caveat is that anything that the project _releases_ probably
deserves the same treatment as code. If however that's not part of
your release. Publication isn't a release - and as you point out, we
have copious wiki examples, official blog entries, and others that
aren't part of a code-like release.
Apologies for not catching on earlier, thanks for illuminating me.
--David
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Perhaps we are in violent agreement, David. If so, then we see R-T-C
applying to "code" and change committed as being by committers. If we are
seeing eye to eye wed would understand that documentation, while an
important asset, is not usually under the same formalities as code. If it
were, apache run wikis and indeed most doc updates couldn't operate as they
do. If we agree to this than R-T-C is a policy that was made for code and
rarely applies to documentation.
As your note seems to imply an equal replacement of terms like committer or
developer with the word contributor, and documentation with code, I think
we don't violently agree, though it is possible we are talking at each
other.
>From a process perspective, I believe documentation can operate as
code. I'm not dismissing this potential and I'm aware of tools to
facilitate that. I believe operating docs as code is a choice, but not the
only choice. It is an optimization.
Do you understand why one might call a vote on a process for documentation
and contributors, if we believed that C-T-R or R-T-C was focused on code
and committers?
I know it is possible to pull technicalities and use rules to say whatever
we want them to. I'm not trying to get into a technicality fight here. I
want to be able to operate in this project and facilitate docs like other
projects. If agreeing with you allows this conversation to stop and
doesn't reverse the intent of the vote then. I agree.
On Sunday, May 19, 2013, David Nalley wrote:
> On Sun, May 19, 2013 at 11:21 AM, Adrian Cole <adrian.f.cole@gmail.com<javascript:;>>
> wrote:
> > David,
> >
> > The vote was for "Do not enforce review on documentation maintenance by
> > contributors". It was not a vote for C-T-R.
> >
> > I understand that Matt and Becca are very unhappy with this idea.
> > Possibly, you've also changed your mind.
> >
> > Is it correct for us to change this to a vote for C-T-R when there is an
> > overwhelming majority in favor of the existing vote? What does
> meritocracy
> > mean when those who've written most of docs votes are changed to a
> > different policy when someone who's not written any starts a thread like
> > this?
> >
> > I understand we probably would like to stop the bleeding, but I don't see
> > the point in a procedural vote if this is the result.
> >
> > -A
> >
>
>
> Adrian:
>
> I feel like we are talking past each other in this particular
> exercise, and are perhaps in violent agreement. :)
>
> Keep in mind RFC 2119 definitions here, to make things a bit more clear.
>
> Under CTR individuals _MAY_ review the code after committed. They
> _MAY_ also remain silent. There is no _REQUIREMENT_ to review under
> CTR. The key element in CTR is that 'developers can make changes at
> will' [1] with the acknowledged possibilities that issues may creep
> in, and that those issues may need to be rectified even after
> committed.
> The original email (which you referenced below says 'neither
> _REQUIRING_ review before or after...') (emphasis added by me to call
> attention to the reference definition) which I think is perhaps key to
> my confusion. I guess my question is - how is this proposal not like
> CTR?
>
> Regardless of model (RTC, CTR, $something_else) contributors,
> committers, and (P)PMC members _SHOULD_ be watching commits. In
> particular (P)PMC members, specifically, are _REQUIRED_ to bear the
> responsibility of IP and copyright governance for the project.
>
> --David
>
> [1] http://www.apache.org/foundation/glossary.html
>
Re: Documentation and what's next
Posted by David Nalley <da...@gnsa.us>.
On Sun, May 19, 2013 at 11:21 AM, Adrian Cole <ad...@gmail.com> wrote:
> David,
>
> The vote was for "Do not enforce review on documentation maintenance by
> contributors". It was not a vote for C-T-R.
>
> I understand that Matt and Becca are very unhappy with this idea.
> Possibly, you've also changed your mind.
>
> Is it correct for us to change this to a vote for C-T-R when there is an
> overwhelming majority in favor of the existing vote? What does meritocracy
> mean when those who've written most of docs votes are changed to a
> different policy when someone who's not written any starts a thread like
> this?
>
> I understand we probably would like to stop the bleeding, but I don't see
> the point in a procedural vote if this is the result.
>
> -A
>
Adrian:
I feel like we are talking past each other in this particular
exercise, and are perhaps in violent agreement. :)
Keep in mind RFC 2119 definitions here, to make things a bit more clear.
Under CTR individuals _MAY_ review the code after committed. They
_MAY_ also remain silent. There is no _REQUIREMENT_ to review under
CTR. The key element in CTR is that 'developers can make changes at
will' [1] with the acknowledged possibilities that issues may creep
in, and that those issues may need to be rectified even after
committed.
The original email (which you referenced below says 'neither
_REQUIRING_ review before or after...') (emphasis added by me to call
attention to the reference definition) which I think is perhaps key to
my confusion. I guess my question is - how is this proposal not like
CTR?
Regardless of model (RTC, CTR, $something_else) contributors,
committers, and (P)PMC members _SHOULD_ be watching commits. In
particular (P)PMC members, specifically, are _REQUIRED_ to bear the
responsibility of IP and copyright governance for the project.
--David
[1] http://www.apache.org/foundation/glossary.html
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Hi, Becca.
I think it is clear that you are finding your way here. I imprecisely
lumped your sentiment into the "very unhappy" category in reaction to
your comment about being "a bit floored" initially. I suppose I could
have more precisely mentioned that two of our committers have
expressed concern, or better to restate each sentiment by dissenters
in isolation. Apologies.
-A
On Sun, May 19, 2013 at 10:20 AM, Becca Wood <si...@gmail.com> wrote:
> Thank you for clarifying this for me. It is true that I don't believe
> there should be no reviewing process whatsoever, but that is just my
> opinion. So I understand now that this is not C-T-R either. Is there any
> way to give feedback to someone through this new approach? I'm not trying
> to be nit picky. I am happy to provide wording and small corrections on my
> own without bothering anyone about it. Please note that I was not the one
> who said every comment == revert. I am not interested in reverting docs or
> anything for that matter without exceptional circumstances.
>
> I guess what I am trying to figure out is how this process works. Can you
> please throw out your misconception that I am trying to be difficult and
> that I am very upset or angry? All I know is what I am inferring from the
> things you have written. I am simply trying to understand.
>
> I have never viewed my role as policing the docs, and I am sorry that there
> is that perception. I don't believe that this was all my fault, but I am
> at least at fault for not communicating that I was not an authoritative
> figure. It was how the process came down the pipe after the large overhaul
> I did on docs.
>
> What I was attempting to say in my message is that if I did all of the work
> for docs (more than wording correction) myself, I would need to dedicate a
> large amount of time that neither I nor anyone else has for this
> considering our needs for full time employment and personal lives. I would
> prefer to work with our community and contributors harmoniously. I enjoy a
> team environment. I'm not interested in working on this alone. I would
> like to help others and for them to help me.
>
> I agree with you that I would like for docs to be very approachable. Folks
> should feel encouraged to contribute to docs. I don't want there to be
> unspoken tensions between us. So now that I have a better understanding of
> what this whole vote was actually supposed to be about, I guess I need to
> understand how the new process works so I can figure out the best ways for
> me to contribute.
Re: Documentation and what's next
Posted by Becca Wood <si...@gmail.com>.
Thank you for clarifying this for me. It is true that I don't believe
there should be no reviewing process whatsoever, but that is just my
opinion. So I understand now that this is not C-T-R either. Is there any
way to give feedback to someone through this new approach? I'm not trying
to be nit picky. I am happy to provide wording and small corrections on my
own without bothering anyone about it. Please note that I was not the one
who said every comment == revert. I am not interested in reverting docs or
anything for that matter without exceptional circumstances.
I guess what I am trying to figure out is how this process works. Can you
please throw out your misconception that I am trying to be difficult and
that I am very upset or angry? All I know is what I am inferring from the
things you have written. I am simply trying to understand.
I have never viewed my role as policing the docs, and I am sorry that there
is that perception. I don't believe that this was all my fault, but I am
at least at fault for not communicating that I was not an authoritative
figure. It was how the process came down the pipe after the large overhaul
I did on docs.
What I was attempting to say in my message is that if I did all of the work
for docs (more than wording correction) myself, I would need to dedicate a
large amount of time that neither I nor anyone else has for this
considering our needs for full time employment and personal lives. I would
prefer to work with our community and contributors harmoniously. I enjoy a
team environment. I'm not interested in working on this alone. I would
like to help others and for them to help me.
I agree with you that I would like for docs to be very approachable. Folks
should feel encouraged to contribute to docs. I don't want there to be
unspoken tensions between us. So now that I have a better understanding of
what this whole vote was actually supposed to be about, I guess I need to
understand how the new process works so I can figure out the best ways for
me to contribute.
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Understanding we're not likely to want to sabotage a legitimate vote
and also want you and matt's concerns at least answered to. Let's
rebase to there we are at.
Here is what the vote was about:
http://markmail.org/thread/n5jioeo6msw2f4nr
> As discussed in the thread "Documentation and what's next", this is a
> procedural vote to neither require review before (C-T-R) or after (R-T-C)
> documentation maintenance performed by Contributors.
>
> Voting in favor of this does block requests for review. Neither does
> voting for this imply we cannot reverse offensive documentation.
As you mentioned in your email, we want documentation to be
approachable. It currently isn't, and warning contributors that if
they don't comply with every comment == revert doesn't make things
approachable. We've tried high levels of control on documentation
before ASF and our documentation stalled except those with enough time
and tenacity to push through change, and overcome roadblock of review
delays, ESL, etc.
Documentation includes wikis (blogs) and git repositories. The fact
that some docs (like readmes and release notes) are in a git repo
doesn't mean we should pull technicalities and say all docs are C-T-R.
The overarching goal is to be able to express trust in our committers
and welcome docs into the project. Docs are not code in so far as you
don't need to know how to write java to contribute or fix them. This
model is less strict and doesn't require us to redirect time for
each-other or the contributor to treat every doc niggle as an issue.
We cannot denial of service the project for a poorly worded doc.
There are other ways, for example helping the person or correcting it.
This doesn't mean just you, either, and I don't want you or anyone
feeling that poor wording correction is a full time job, or that they
have police duty. The whole point is to remove this tension from the
normal path.
We are probably coming from similar places (ex. wanting the project to
have good docs) and optimizing for different areas of concern. I
don't think our docs is a fulltime job, if it were more approachable
and less strict. In short, this is what this vote is intended to do.
-A
On Sun, May 19, 2013 at 9:01 AM, Becca Wood <si...@gmail.com> wrote:
> Adrian,
>
> Forgive my bluntness here, but I need for you to be very clear with what
> are suggesting because I thought that you were speaking of changing the
> process to C-T-R.
>
> A conflict exists in my mind between the things that you have written and
> the information that you cut and pasted into your messages. You pasted the
> definitions for R-T-C, C-T-R, and Vetoing. Please forgive me if I am
> wrong, but I believe that David and Matt are also confused by your meaning.
> Are you suggesting that we have no reviewing process at all on
> documentation?
>
> I would also appreciate it if you read what I have written instead of
> looping my opinion in with others' opinions in the future. I am not "very
> unhappy." I said I had reservations about C-T-R, but that I am willing to
> adapt to the needs of the community.
>
> Becca
Re: Documentation and what's next
Posted by Becca Wood <si...@gmail.com>.
Adrian,
Forgive my bluntness here, but I need for you to be very clear with what
are suggesting because I thought that you were speaking of changing the
process to C-T-R.
A conflict exists in my mind between the things that you have written and
the information that you cut and pasted into your messages. You pasted the
definitions for R-T-C, C-T-R, and Vetoing. Please forgive me if I am
wrong, but I believe that David and Matt are also confused by your meaning.
Are you suggesting that we have no reviewing process at all on
documentation?
I would also appreciate it if you read what I have written instead of
looping my opinion in with others' opinions in the future. I am not "very
unhappy." I said I had reservations about C-T-R, but that I am willing to
adapt to the needs of the community.
Becca
Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
David,
The vote was for "Do not enforce review on documentation maintenance by
contributors". It was not a vote for C-T-R.
I understand that Matt and Becca are very unhappy with this idea.
Possibly, you've also changed your mind.
Is it correct for us to change this to a vote for C-T-R when there is an
overwhelming majority in favor of the existing vote? What does meritocracy
mean when those who've written most of docs votes are changed to a
different policy when someone who's not written any starts a thread like
this?
I understand we probably would like to stop the bleeding, but I don't see
the point in a procedural vote if this is the result.
-A
On Sunday, May 19, 2013, David Nalley wrote:
> On Sun, May 19, 2013 at 3:53 AM, Matt Stephenson <ma...@apache.org>
> wrote:
> > So, I'd like to understand the differences between what we're saying here
> > and what commit-then-review would actually be. If we're going to do CTR
> > I'm happy, but what I'm hearing is that we want to avoid reviewing
> changes
> > altogether. If we just want it to be optional to do a review, that's
> what
> > CTR offers.
> >
> > This all seems like tons of weird process bikeshedding. Can a project
> > actually have a repo in ASF where we declare that it's against the rules
> to
> > review changes on it? That seems to be the only difference, that we're
> > removing the potential for an optional review on a change. Can't we just
> > say CTR and be done with this?
> >
> >
>
> I reread this thread - and I think CTR seems to be the consensus here,
> even though we're now 30+ messages in, and perhaps the topic has
> shifted.
>
> To your question, I can't personally imagine a process where you can't
> review changes. I did reread all of this to see if I missed something,
> and I don't seem to catch the commit-then-nothing inferences.
>
> --David
>
Re: Documentation and what's next
Posted by David Nalley <da...@gnsa.us>.
On Sun, May 19, 2013 at 3:53 AM, Matt Stephenson <ma...@apache.org> wrote:
> So, I'd like to understand the differences between what we're saying here
> and what commit-then-review would actually be. If we're going to do CTR
> I'm happy, but what I'm hearing is that we want to avoid reviewing changes
> altogether. If we just want it to be optional to do a review, that's what
> CTR offers.
>
> This all seems like tons of weird process bikeshedding. Can a project
> actually have a repo in ASF where we declare that it's against the rules to
> review changes on it? That seems to be the only difference, that we're
> removing the potential for an optional review on a change. Can't we just
> say CTR and be done with this?
>
>
I reread this thread - and I think CTR seems to be the consensus here,
even though we're now 30+ messages in, and perhaps the topic has
shifted.
To your question, I can't personally imagine a process where you can't
review changes. I did reread all of this to see if I missed something,
and I don't seem to catch the commit-then-nothing inferences.
--David
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
So, I'd like to understand the differences between what we're saying here
and what commit-then-review would actually be. If we're going to do CTR
I'm happy, but what I'm hearing is that we want to avoid reviewing changes
altogether. If we just want it to be optional to do a review, that's what
CTR offers.
This all seems like tons of weird process bikeshedding. Can a project
actually have a repo in ASF where we declare that it's against the rules to
review changes on it? That seems to be the only difference, that we're
removing the potential for an optional review on a change. Can't we just
say CTR and be done with this?
On Sat, May 18, 2013 at 7:40 PM, David Nalley <da...@gnsa.us> wrote:
> On Sat, May 18, 2013 at 9:44 PM, Matt Stephenson <ma...@apache.org>
> wrote:
> > So we voted on asking for the review to not be mandatory, if someone
> > reviews your work, you should still be required to respond to that
> review,
> > correct?
> >
>
> I am personally hesitant to use the word required.
> That said, if folks don't or won't communicate there is a much bigger
> problem than inaccurate docs.
> If we start having a problem with people going silent, as a community
> we'll have to deal with it, but I don't think we will.
>
>
>
> > Are you asking for us to no longer be required to respond to review
> > feedback on docs commits?
> >
>
> I haven't interpreted that from this thread - just lowering the
> barrier in this particular area to increase rate of contribution.
>
> > That sounds really rude to those that take the time to do reviews. I
> > personally will always respond to review feedback.
> >
> >
> > On Sat, May 18, 2013 at 6:15 PM, Matt Stephenson <mattstep@mattstep.net
> >wrote:
> >
> >> So, the past few days have been very busy, so I'm still not clear on
> what
> >> you're asking for.
> >>
> >> It sounds like you're asking for commit-then-nothing for docs. Is that
> >> correct?
> >>
>
> --David
>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
So, I'd like to understand the differences between what we're saying here
and what commit-then-review would actually be. If we're going to do
commit-then-review I'm happy, but what I'm hearing is that we want to avoid
reviewing changes altogether.
This means someone shouldn't offer feedback on a change? That's all
commit-then-review is. Am I missing something here?
I guess with the time limits, I've got to decide if I'm going to veto the
other vote? This all seems like tons of weird process bikeshedding. Can a
project actually have a repo in ASF where we declare that it's against the
rules to review changes on it?
On Sat, May 18, 2013 at 7:40 PM, David Nalley <da...@gnsa.us> wrote:
> On Sat, May 18, 2013 at 9:44 PM, Matt Stephenson <ma...@apache.org>
> wrote:
> > So we voted on asking for the review to not be mandatory, if someone
> > reviews your work, you should still be required to respond to that
> review,
> > correct?
> >
>
> I am personally hesitant to use the word required.
> That said, if folks don't or won't communicate there is a much bigger
> problem than inaccurate docs.
> If we start having a problem with people going silent, as a community
> we'll have to deal with it, but I don't think we will.
>
>
>
> > Are you asking for us to no longer be required to respond to review
> > feedback on docs commits?
> >
>
> I haven't interpreted that from this thread - just lowering the
> barrier in this particular area to increase rate of contribution.
>
> > That sounds really rude to those that take the time to do reviews. I
> > personally will always respond to review feedback.
> >
> >
> > On Sat, May 18, 2013 at 6:15 PM, Matt Stephenson <mattstep@mattstep.net
> >wrote:
> >
> >> So, the past few days have been very busy, so I'm still not clear on
> what
> >> you're asking for.
> >>
> >> It sounds like you're asking for commit-then-nothing for docs. Is that
> >> correct?
> >>
>
> --David
>
Re: Documentation and what's next
Posted by Becca Wood <si...@gmail.com>.
I have been giving this change in methodology careful consideration since
it appeared yesterday. I admit that I was a bit floored when Adrian made
the suggestion that we should change our process to be C-T-R. I still feel
apprehensive about this approach, but I have decided that I can see where
there may be some benefits. This is especially true considering that I
have been the only person amongst the jclouds committers so far that is
solely dedicated to documentation.
Much as I wish that I could keep up with documenting all processes,
revising and updating existing docs, and reviewing each commit that comes
through, I recognize that an enormous amount of time will be needed to do
all of the above AND keep things constantly updated. It is easily the
amount of time required for a full time job. This is why we have and need
a community.
I would like to help build the community around jclouds, and I wish to
attract more contributors. I do not want folks to be afraid of
contributing to documentation. I appreciate any contributions to jclouds
and also any help that others give me when I am griding out docs. It is a
challenging task and something that I have found to be very rewarding. I
have never intended to snag folks up when reviewing their contributions to
jclouds documentation. I do admit a penchant for being thorough, and I
recognize that I haven't always been as timely with things as I would like
to be.
While I do hold reservations about this approach and the possibility of it
leading to some sloppiness within documentation, I am willing to adapt to
the needs of our community. I would like to build stronger relationships
with our current community members and attract more folks to jclouds. I
have only just begun my relationship with Apache, but it seems to me that
innovation through community is something that is embraced. If this change
is being made with the good of community in mind, then I am willing to find
ways to work in this new environment.
I also agree with what David has said here. If people stop responding to
each other, discussions go silent, and issues remain unsolved, we have
bigger issues within our project than a few bugs here and there. So long
as we're all willing to work together and generally respect each other even
while we have differences of opinion, I see no reason that we cannot
continue working together with this new methodology in place.
On Sat, May 18, 2013 at 7:40 PM, David Nalley <da...@gnsa.us> wrote:
> On Sat, May 18, 2013 at 9:44 PM, Matt Stephenson <ma...@apache.org>
> wrote:
> > So we voted on asking for the review to not be mandatory, if someone
> > reviews your work, you should still be required to respond to that
> review,
> > correct?
> >
>
> I am personally hesitant to use the word required.
> That said, if folks don't or won't communicate there is a much bigger
> problem than inaccurate docs.
> If we start having a problem with people going silent, as a community
> we'll have to deal with it, but I don't think we will.
>
>
>
> > Are you asking for us to no longer be required to respond to review
> > feedback on docs commits?
> >
>
> I haven't interpreted that from this thread - just lowering the
> barrier in this particular area to increase rate of contribution.
>
> > That sounds really rude to those that take the time to do reviews. I
> > personally will always respond to review feedback.
> >
> >
> > On Sat, May 18, 2013 at 6:15 PM, Matt Stephenson <mattstep@mattstep.net
> >wrote:
> >
> >> So, the past few days have been very busy, so I'm still not clear on
> what
> >> you're asking for.
> >>
> >> It sounds like you're asking for commit-then-nothing for docs. Is that
> >> correct?
> >>
>
> --David
>
Re: Documentation and what's next
Posted by David Nalley <da...@gnsa.us>.
On Sat, May 18, 2013 at 9:44 PM, Matt Stephenson <ma...@apache.org> wrote:
> So we voted on asking for the review to not be mandatory, if someone
> reviews your work, you should still be required to respond to that review,
> correct?
>
I am personally hesitant to use the word required.
That said, if folks don't or won't communicate there is a much bigger
problem than inaccurate docs.
If we start having a problem with people going silent, as a community
we'll have to deal with it, but I don't think we will.
> Are you asking for us to no longer be required to respond to review
> feedback on docs commits?
>
I haven't interpreted that from this thread - just lowering the
barrier in this particular area to increase rate of contribution.
> That sounds really rude to those that take the time to do reviews. I
> personally will always respond to review feedback.
>
>
> On Sat, May 18, 2013 at 6:15 PM, Matt Stephenson <ma...@mattstep.net>wrote:
>
>> So, the past few days have been very busy, so I'm still not clear on what
>> you're asking for.
>>
>> It sounds like you're asking for commit-then-nothing for docs. Is that
>> correct?
>>
--David
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
So we voted on asking for the review to not be mandatory, if someone
reviews your work, you should still be required to respond to that review,
correct?
Are you asking for us to no longer be required to respond to review
feedback on docs commits?
That sounds really rude to those that take the time to do reviews. I
personally will always respond to review feedback.
On Sat, May 18, 2013 at 6:15 PM, Matt Stephenson <ma...@mattstep.net>wrote:
> So, the past few days have been very busy, so I'm still not clear on what
> you're asking for.
>
> It sounds like you're asking for commit-then-nothing for docs. Is that
> correct?
>
>
> On Sat, May 18, 2013 at 12:08 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> Matt, I'm happy you have mentioned jclouds in your presentations, and
>> hope that what you perceive as imperfect won't stunt that. Your
>> presentations reach plenty of people, and help grow the community. No
>> doubt.
>>
>> I think we need to understand the outstanding vote better:
>>
>> Do not enforce review on documentation maintenance by contributors
>>
>> In other words, Vetos and reverts are not a consideration for docs, as
>> they would be if governed by C-T-R.
>>
>> If we follow the ASF process and accept a majority vote for this
>> process, it wouldn't be appropriate to for you or anyone else to
>> expect me to revert someone's poorly worded doc. If I found something
>> like this, I'd correct it and cc the person.
>>
>> It is clear we don't have the same opinion on this; I understand that
>> is disappointing. I'm sure there will be a vote sometime I have a
>> strong opinion on that isn't the majority one. I'd probably feel
>> frustrated about that, too. I empathize with your situation, and hope
>> you can find enough value in the apache way to accept majority rule.
>>
>> -A
>>
>> On Sat, May 18, 2013 at 11:09 AM, Matt Stephenson <ma...@mattstep.net>
>> wrote:
>> > I disagree that people should be making changes without that concern. I
>> > hold this project to a high bar, I speak publicly about it, and as a
>> result
>> > the quality of the documentation has a bearing on my own career. I
>> refuse
>> > to allow poorly written documentation to continue, nor do I expect
>> anyone
>> > to go "fixing up" other people's poorly worded docs. If it doesn't meet
>> > the bar, it needs to be fixed, and if it doesn't get fixed, it needs to
>> be
>> > reverted. We should treat this just like any other repository, and not
>> > make an exception for it. If someone submitted code that was poorly
>> > written and refused to fix it, I would expect you to revert that kind of
>> > change.
>> >
>> > Matt
>> >
>> >
>> > On Sat, May 18, 2013 at 10:31 AM, Adrian Cole <adrian.f.cole@gmail.com
>> >wrote:
>> >
>> >> Vetos only apply we are acting in a Review-Then-Commit or
>> >> Commit-Then-Review mode, which doesn't apply to the outstanding vote
>> >> on documentation. So, I think it is safe to say that in the case of
>> >> docs, people shouldn't have fear of other people reverting their
>> >> update, though clearly it is possible for any of us to commit
>> >> something to undo the last doc update.
>> >>
>> >> I really hope we can establish a positive culture for docs that
>> >> assumes change is for the better, and those making it have cause to do
>> >> so. Those of us improving docs in response to users shouldn't have to
>> >> worry about those updates being reverted without an extremely
>> >> important justification. We should all focus on moving forward change
>> >> vs how we can block them.
>> >>
>> >> -A
>> >>
>> >> http://www.apache.org/foundation/glossary.html#Veto
>> >>
>> >> On Sat, May 18, 2013 at 9:13 AM, Matt Stephenson <
>> mattstep@mattstep.net>
>> >> wrote:
>> >> > The bar is still high on doc changes. In this model, ignoring review
>> >> > comments can result in your changes being reverted. It can be a much
>> >> more
>> >> > difficult experience for some documentarians.
>> >> > On May 17, 2013 5:54 PM, "Everett Toews" <
>> everett.toews@rackspace.com>
>> >> > wrote:
>> >> >
>> >> >> I think this provides a better path to incremental doc improvement.
>> It
>> >> >> also lowers the barrier for people who only want to contribute doc.
>> >> >>
>> >> >> Everett
>> >> >>
>> >> >> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
>> >> >>
>> >> >> > I hear you, and I especially like moving the majority of the
>> "thrashy
>> >> >> docs"
>> >> >> > to wikis.
>> >> >> >
>> >> >> > The intent here is to establish a procedure knowing we aren't
>> staffed
>> >> to
>> >> >> do
>> >> >> > reviews of every doc update in a central fashion. We all want
>> good
>> >> docs,
>> >> >> > and we can't let best be the enemy of that. Though not
>> necessarily
>> >> the
>> >> >> > case with you and others like Becca, folks contributing docs are
>> >> doing so
>> >> >> > in response to user problems or code shifts. Bad docs are
>> important
>> >> to
>> >> >> fix
>> >> >> > in a very timely fashion. We need folks with the right sort of
>> >> pressures
>> >> >> > to make the important fixes at the same time without precluding
>> later
>> >> >> > grammar, etc revisions by those who feel strongly about them. It
>> is
>> >> >> > possible that most of the fixes I mention fall into the "move to
>> wiki"
>> >> >> > category you mention.
>> >> >> >
>> >> >> > We have a couple things going on in this thread. One is how
>> >> centralized
>> >> >> > our docs are and the tech we use to maintain it. We'll surely
>> have a
>> >> lot
>> >> >> > of opinions on that. Another is procedural: review before commit
>> on
>> >> docs
>> >> >> > vs review after.
>> >> >> >
>> >> >> > Regardless, I believe it is better to trust those who contribute
>> docs
>> >> and
>> >> >> > fixes first, and adjust later vs review before commit. This
>> >> procedure is
>> >> >> > very common across open source projects and also many companies.
>> It
>> >> does
>> >> >> > carry the risks you mention about a possible bad doc getting in.
>> >> >> >
>> >> >> > Unless there's an overwhelming sense we won't have a majority
>> buy-in
>> >> for
>> >> >> > that through this thread, I plan to call for a procedural vote to
>> not
>> >> >> > require review before commit on docs.
>> >> >> >
>> >> >> > -A
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <
>> >> mattstep@mattstep.net
>> >> >> >wrote:
>> >> >> >
>> >> >> >> IMHO, its hard to catch up on docs when it goes south. The
>> process
>> >> we
>> >> >> have
>> >> >> >> in my day job is this : doc is written/updated and sent for
>> review,
>> >> tech
>> >> >> >> writer reviews and typically the feedback is that the change
>> needs
>> >> to be
>> >> >> >> applied to other docs too. This helps expand the documentation.
>> >> >> >>
>> >> >> >> I believe that we have a good deal of docs that shouldn't be in
>> the
>> >> main
>> >> >> >> doc tree for jclouds. The docs pertaining to contributing could
>> >> easily
>> >> >> be
>> >> >> >> moved to the wiki.
>> >> >> >>
>> >> >> >> Its easy to look at the actions that created the docs as
>> potential
>> >> >> >> problems, but in my experience its the inaction. When people
>> half
>> >> ass
>> >> >> >> their way through a doc, or a code change happens without a doc
>> >> change
>> >> >> due
>> >> >> >> to laziness, things slip.
>> >> >> >>
>> >> >> >> Docs are more important than code, and they should be treated as
>> >> such.
>> >> >> I
>> >> >> >> see many times review feedback isn't promptly dealt with and
>> overall
>> >> >> >> attention to detail is lost.
>> >> >> >>
>> >> >> >> I hope we come up with an easy process that doesnt lead to
>> laziness.
>> >> >> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com>
>> >> wrote:
>> >> >> >>
>> >> >> >>> Hi, team.
>> >> >> >>>
>> >> >> >>> Since jclouds started, we've had many waves of doc efforts and
>> >> >> approach.
>> >> >> >> We
>> >> >> >>> started with google wiki. It looked great and easy to update
>> and
>> >> >> control
>> >> >> >>> access to. When we moved to GitHub we found access control
>> absent
>> >> >> which
>> >> >> >>> led to Vijays hard work converting to markdown and hosting on
>> github
>> >> >> >> pages.
>> >> >> >>> While some had patience to submit pull requests, our docs did
>> rot.
>> >> >> >> Becca
>> >> >> >>> helped reface our website and spent a lot of effort to renovate
>> >> select
>> >> >> >>> documents and organized docs. She also removed the chance to
>> >> >> completely
>> >> >> >>> break the website due to accidentally breaking Jekyll.
>> Meanwhile
>> >> the
>> >> >> >>> burden of fixing docs increased due to a combination of stricter
>> >> >> >>> grammatical review and a perception that only Becca can approve
>> >> things.
>> >> >> >>> The commit log shows those tenacious enough can have content
>> merged
>> >> in
>> >> >> a
>> >> >> >>> couple weeks or so.
>> >> >> >>>
>> >> >> >>> Meanwhile, docs are often hard to find or broken. When I nudge
>> >> someone
>> >> >> >> to
>> >> >> >>> fix something, it is very rare when they open a pull request and
>> >> rarer
>> >> >> >> that
>> >> >> >>> being merged within a week.
>> >> >> >>>
>> >> >> >>> No one is at fault here, but I feel we've collectively boiled
>> the
>> >> frog.
>> >> >> >> I
>> >> >> >>> hope we can discuss this topic without anyone feeling attacked.
>> >> This
>> >> >> is
>> >> >> >>> just reflection.
>> >> >> >>>
>> >> >> >>> It should be easy to find, correct, and update docs. I work
>> with
>> >> many
>> >> >> >>> projects and ours is by far the hardest to deal with. Something
>> >> has to
>> >> >> >>> give, and I'm apprehensive about fork lifting our old docs and
>> >> process
>> >> >> >> into
>> >> >> >>> the ASF.
>> >> >> >>>
>> >> >> >>> Personally, I really would love to use processes similar to what
>> >> other
>> >> >> >>> projects use for docs rather than being a snowflake. I desire
>> less
>> >> >> >>> friction, explaining, bottlenecks, special instructions and
>> gotchas.
>> >> >> >>>
>> >> >> >>> Do others feel this way? What options are on the table for
>> doing
>> >> >> >>> documentation in the ASF?
>> >> >> >>>
>> >> >> >>> -A
>> >> >> >>>
>> >> >> >>
>> >> >>
>> >> >>
>> >>
>>
>
>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
So, the past few days have been very busy, so I'm still not clear on what
you're asking for.
It sounds like you're asking for commit-then-nothing for docs. Is that
correct?
On Sat, May 18, 2013 at 12:08 PM, Adrian Cole <ad...@gmail.com>wrote:
> Matt, I'm happy you have mentioned jclouds in your presentations, and
> hope that what you perceive as imperfect won't stunt that. Your
> presentations reach plenty of people, and help grow the community. No
> doubt.
>
> I think we need to understand the outstanding vote better:
>
> Do not enforce review on documentation maintenance by contributors
>
> In other words, Vetos and reverts are not a consideration for docs, as
> they would be if governed by C-T-R.
>
> If we follow the ASF process and accept a majority vote for this
> process, it wouldn't be appropriate to for you or anyone else to
> expect me to revert someone's poorly worded doc. If I found something
> like this, I'd correct it and cc the person.
>
> It is clear we don't have the same opinion on this; I understand that
> is disappointing. I'm sure there will be a vote sometime I have a
> strong opinion on that isn't the majority one. I'd probably feel
> frustrated about that, too. I empathize with your situation, and hope
> you can find enough value in the apache way to accept majority rule.
>
> -A
>
> On Sat, May 18, 2013 at 11:09 AM, Matt Stephenson <ma...@mattstep.net>
> wrote:
> > I disagree that people should be making changes without that concern. I
> > hold this project to a high bar, I speak publicly about it, and as a
> result
> > the quality of the documentation has a bearing on my own career. I
> refuse
> > to allow poorly written documentation to continue, nor do I expect anyone
> > to go "fixing up" other people's poorly worded docs. If it doesn't meet
> > the bar, it needs to be fixed, and if it doesn't get fixed, it needs to
> be
> > reverted. We should treat this just like any other repository, and not
> > make an exception for it. If someone submitted code that was poorly
> > written and refused to fix it, I would expect you to revert that kind of
> > change.
> >
> > Matt
> >
> >
> > On Sat, May 18, 2013 at 10:31 AM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
> >
> >> Vetos only apply we are acting in a Review-Then-Commit or
> >> Commit-Then-Review mode, which doesn't apply to the outstanding vote
> >> on documentation. So, I think it is safe to say that in the case of
> >> docs, people shouldn't have fear of other people reverting their
> >> update, though clearly it is possible for any of us to commit
> >> something to undo the last doc update.
> >>
> >> I really hope we can establish a positive culture for docs that
> >> assumes change is for the better, and those making it have cause to do
> >> so. Those of us improving docs in response to users shouldn't have to
> >> worry about those updates being reverted without an extremely
> >> important justification. We should all focus on moving forward change
> >> vs how we can block them.
> >>
> >> -A
> >>
> >> http://www.apache.org/foundation/glossary.html#Veto
> >>
> >> On Sat, May 18, 2013 at 9:13 AM, Matt Stephenson <mattstep@mattstep.net
> >
> >> wrote:
> >> > The bar is still high on doc changes. In this model, ignoring review
> >> > comments can result in your changes being reverted. It can be a much
> >> more
> >> > difficult experience for some documentarians.
> >> > On May 17, 2013 5:54 PM, "Everett Toews" <everett.toews@rackspace.com
> >
> >> > wrote:
> >> >
> >> >> I think this provides a better path to incremental doc improvement.
> It
> >> >> also lowers the barrier for people who only want to contribute doc.
> >> >>
> >> >> Everett
> >> >>
> >> >> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
> >> >>
> >> >> > I hear you, and I especially like moving the majority of the
> "thrashy
> >> >> docs"
> >> >> > to wikis.
> >> >> >
> >> >> > The intent here is to establish a procedure knowing we aren't
> staffed
> >> to
> >> >> do
> >> >> > reviews of every doc update in a central fashion. We all want good
> >> docs,
> >> >> > and we can't let best be the enemy of that. Though not necessarily
> >> the
> >> >> > case with you and others like Becca, folks contributing docs are
> >> doing so
> >> >> > in response to user problems or code shifts. Bad docs are
> important
> >> to
> >> >> fix
> >> >> > in a very timely fashion. We need folks with the right sort of
> >> pressures
> >> >> > to make the important fixes at the same time without precluding
> later
> >> >> > grammar, etc revisions by those who feel strongly about them. It
> is
> >> >> > possible that most of the fixes I mention fall into the "move to
> wiki"
> >> >> > category you mention.
> >> >> >
> >> >> > We have a couple things going on in this thread. One is how
> >> centralized
> >> >> > our docs are and the tech we use to maintain it. We'll surely
> have a
> >> lot
> >> >> > of opinions on that. Another is procedural: review before commit
> on
> >> docs
> >> >> > vs review after.
> >> >> >
> >> >> > Regardless, I believe it is better to trust those who contribute
> docs
> >> and
> >> >> > fixes first, and adjust later vs review before commit. This
> >> procedure is
> >> >> > very common across open source projects and also many companies.
> It
> >> does
> >> >> > carry the risks you mention about a possible bad doc getting in.
> >> >> >
> >> >> > Unless there's an overwhelming sense we won't have a majority
> buy-in
> >> for
> >> >> > that through this thread, I plan to call for a procedural vote to
> not
> >> >> > require review before commit on docs.
> >> >> >
> >> >> > -A
> >> >> >
> >> >> >
> >> >> >
> >> >> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <
> >> mattstep@mattstep.net
> >> >> >wrote:
> >> >> >
> >> >> >> IMHO, its hard to catch up on docs when it goes south. The
> process
> >> we
> >> >> have
> >> >> >> in my day job is this : doc is written/updated and sent for
> review,
> >> tech
> >> >> >> writer reviews and typically the feedback is that the change needs
> >> to be
> >> >> >> applied to other docs too. This helps expand the documentation.
> >> >> >>
> >> >> >> I believe that we have a good deal of docs that shouldn't be in
> the
> >> main
> >> >> >> doc tree for jclouds. The docs pertaining to contributing could
> >> easily
> >> >> be
> >> >> >> moved to the wiki.
> >> >> >>
> >> >> >> Its easy to look at the actions that created the docs as potential
> >> >> >> problems, but in my experience its the inaction. When people half
> >> ass
> >> >> >> their way through a doc, or a code change happens without a doc
> >> change
> >> >> due
> >> >> >> to laziness, things slip.
> >> >> >>
> >> >> >> Docs are more important than code, and they should be treated as
> >> such.
> >> >> I
> >> >> >> see many times review feedback isn't promptly dealt with and
> overall
> >> >> >> attention to detail is lost.
> >> >> >>
> >> >> >> I hope we come up with an easy process that doesnt lead to
> laziness.
> >> >> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com>
> >> wrote:
> >> >> >>
> >> >> >>> Hi, team.
> >> >> >>>
> >> >> >>> Since jclouds started, we've had many waves of doc efforts and
> >> >> approach.
> >> >> >> We
> >> >> >>> started with google wiki. It looked great and easy to update and
> >> >> control
> >> >> >>> access to. When we moved to GitHub we found access control
> absent
> >> >> which
> >> >> >>> led to Vijays hard work converting to markdown and hosting on
> github
> >> >> >> pages.
> >> >> >>> While some had patience to submit pull requests, our docs did
> rot.
> >> >> >> Becca
> >> >> >>> helped reface our website and spent a lot of effort to renovate
> >> select
> >> >> >>> documents and organized docs. She also removed the chance to
> >> >> completely
> >> >> >>> break the website due to accidentally breaking Jekyll. Meanwhile
> >> the
> >> >> >>> burden of fixing docs increased due to a combination of stricter
> >> >> >>> grammatical review and a perception that only Becca can approve
> >> things.
> >> >> >>> The commit log shows those tenacious enough can have content
> merged
> >> in
> >> >> a
> >> >> >>> couple weeks or so.
> >> >> >>>
> >> >> >>> Meanwhile, docs are often hard to find or broken. When I nudge
> >> someone
> >> >> >> to
> >> >> >>> fix something, it is very rare when they open a pull request and
> >> rarer
> >> >> >> that
> >> >> >>> being merged within a week.
> >> >> >>>
> >> >> >>> No one is at fault here, but I feel we've collectively boiled the
> >> frog.
> >> >> >> I
> >> >> >>> hope we can discuss this topic without anyone feeling attacked.
> >> This
> >> >> is
> >> >> >>> just reflection.
> >> >> >>>
> >> >> >>> It should be easy to find, correct, and update docs. I work with
> >> many
> >> >> >>> projects and ours is by far the hardest to deal with. Something
> >> has to
> >> >> >>> give, and I'm apprehensive about fork lifting our old docs and
> >> process
> >> >> >> into
> >> >> >>> the ASF.
> >> >> >>>
> >> >> >>> Personally, I really would love to use processes similar to what
> >> other
> >> >> >>> projects use for docs rather than being a snowflake. I desire
> less
> >> >> >>> friction, explaining, bottlenecks, special instructions and
> gotchas.
> >> >> >>>
> >> >> >>> Do others feel this way? What options are on the table for doing
> >> >> >>> documentation in the ASF?
> >> >> >>>
> >> >> >>> -A
> >> >> >>>
> >> >> >>
> >> >>
> >> >>
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Matt, I'm happy you have mentioned jclouds in your presentations, and
hope that what you perceive as imperfect won't stunt that. Your
presentations reach plenty of people, and help grow the community. No
doubt.
I think we need to understand the outstanding vote better:
Do not enforce review on documentation maintenance by contributors
In other words, Vetos and reverts are not a consideration for docs, as
they would be if governed by C-T-R.
If we follow the ASF process and accept a majority vote for this
process, it wouldn't be appropriate to for you or anyone else to
expect me to revert someone's poorly worded doc. If I found something
like this, I'd correct it and cc the person.
It is clear we don't have the same opinion on this; I understand that
is disappointing. I'm sure there will be a vote sometime I have a
strong opinion on that isn't the majority one. I'd probably feel
frustrated about that, too. I empathize with your situation, and hope
you can find enough value in the apache way to accept majority rule.
-A
On Sat, May 18, 2013 at 11:09 AM, Matt Stephenson <ma...@mattstep.net> wrote:
> I disagree that people should be making changes without that concern. I
> hold this project to a high bar, I speak publicly about it, and as a result
> the quality of the documentation has a bearing on my own career. I refuse
> to allow poorly written documentation to continue, nor do I expect anyone
> to go "fixing up" other people's poorly worded docs. If it doesn't meet
> the bar, it needs to be fixed, and if it doesn't get fixed, it needs to be
> reverted. We should treat this just like any other repository, and not
> make an exception for it. If someone submitted code that was poorly
> written and refused to fix it, I would expect you to revert that kind of
> change.
>
> Matt
>
>
> On Sat, May 18, 2013 at 10:31 AM, Adrian Cole <ad...@gmail.com>wrote:
>
>> Vetos only apply we are acting in a Review-Then-Commit or
>> Commit-Then-Review mode, which doesn't apply to the outstanding vote
>> on documentation. So, I think it is safe to say that in the case of
>> docs, people shouldn't have fear of other people reverting their
>> update, though clearly it is possible for any of us to commit
>> something to undo the last doc update.
>>
>> I really hope we can establish a positive culture for docs that
>> assumes change is for the better, and those making it have cause to do
>> so. Those of us improving docs in response to users shouldn't have to
>> worry about those updates being reverted without an extremely
>> important justification. We should all focus on moving forward change
>> vs how we can block them.
>>
>> -A
>>
>> http://www.apache.org/foundation/glossary.html#Veto
>>
>> On Sat, May 18, 2013 at 9:13 AM, Matt Stephenson <ma...@mattstep.net>
>> wrote:
>> > The bar is still high on doc changes. In this model, ignoring review
>> > comments can result in your changes being reverted. It can be a much
>> more
>> > difficult experience for some documentarians.
>> > On May 17, 2013 5:54 PM, "Everett Toews" <ev...@rackspace.com>
>> > wrote:
>> >
>> >> I think this provides a better path to incremental doc improvement. It
>> >> also lowers the barrier for people who only want to contribute doc.
>> >>
>> >> Everett
>> >>
>> >> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
>> >>
>> >> > I hear you, and I especially like moving the majority of the "thrashy
>> >> docs"
>> >> > to wikis.
>> >> >
>> >> > The intent here is to establish a procedure knowing we aren't staffed
>> to
>> >> do
>> >> > reviews of every doc update in a central fashion. We all want good
>> docs,
>> >> > and we can't let best be the enemy of that. Though not necessarily
>> the
>> >> > case with you and others like Becca, folks contributing docs are
>> doing so
>> >> > in response to user problems or code shifts. Bad docs are important
>> to
>> >> fix
>> >> > in a very timely fashion. We need folks with the right sort of
>> pressures
>> >> > to make the important fixes at the same time without precluding later
>> >> > grammar, etc revisions by those who feel strongly about them. It is
>> >> > possible that most of the fixes I mention fall into the "move to wiki"
>> >> > category you mention.
>> >> >
>> >> > We have a couple things going on in this thread. One is how
>> centralized
>> >> > our docs are and the tech we use to maintain it. We'll surely have a
>> lot
>> >> > of opinions on that. Another is procedural: review before commit on
>> docs
>> >> > vs review after.
>> >> >
>> >> > Regardless, I believe it is better to trust those who contribute docs
>> and
>> >> > fixes first, and adjust later vs review before commit. This
>> procedure is
>> >> > very common across open source projects and also many companies. It
>> does
>> >> > carry the risks you mention about a possible bad doc getting in.
>> >> >
>> >> > Unless there's an overwhelming sense we won't have a majority buy-in
>> for
>> >> > that through this thread, I plan to call for a procedural vote to not
>> >> > require review before commit on docs.
>> >> >
>> >> > -A
>> >> >
>> >> >
>> >> >
>> >> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <
>> mattstep@mattstep.net
>> >> >wrote:
>> >> >
>> >> >> IMHO, its hard to catch up on docs when it goes south. The process
>> we
>> >> have
>> >> >> in my day job is this : doc is written/updated and sent for review,
>> tech
>> >> >> writer reviews and typically the feedback is that the change needs
>> to be
>> >> >> applied to other docs too. This helps expand the documentation.
>> >> >>
>> >> >> I believe that we have a good deal of docs that shouldn't be in the
>> main
>> >> >> doc tree for jclouds. The docs pertaining to contributing could
>> easily
>> >> be
>> >> >> moved to the wiki.
>> >> >>
>> >> >> Its easy to look at the actions that created the docs as potential
>> >> >> problems, but in my experience its the inaction. When people half
>> ass
>> >> >> their way through a doc, or a code change happens without a doc
>> change
>> >> due
>> >> >> to laziness, things slip.
>> >> >>
>> >> >> Docs are more important than code, and they should be treated as
>> such.
>> >> I
>> >> >> see many times review feedback isn't promptly dealt with and overall
>> >> >> attention to detail is lost.
>> >> >>
>> >> >> I hope we come up with an easy process that doesnt lead to laziness.
>> >> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com>
>> wrote:
>> >> >>
>> >> >>> Hi, team.
>> >> >>>
>> >> >>> Since jclouds started, we've had many waves of doc efforts and
>> >> approach.
>> >> >> We
>> >> >>> started with google wiki. It looked great and easy to update and
>> >> control
>> >> >>> access to. When we moved to GitHub we found access control absent
>> >> which
>> >> >>> led to Vijays hard work converting to markdown and hosting on github
>> >> >> pages.
>> >> >>> While some had patience to submit pull requests, our docs did rot.
>> >> >> Becca
>> >> >>> helped reface our website and spent a lot of effort to renovate
>> select
>> >> >>> documents and organized docs. She also removed the chance to
>> >> completely
>> >> >>> break the website due to accidentally breaking Jekyll. Meanwhile
>> the
>> >> >>> burden of fixing docs increased due to a combination of stricter
>> >> >>> grammatical review and a perception that only Becca can approve
>> things.
>> >> >>> The commit log shows those tenacious enough can have content merged
>> in
>> >> a
>> >> >>> couple weeks or so.
>> >> >>>
>> >> >>> Meanwhile, docs are often hard to find or broken. When I nudge
>> someone
>> >> >> to
>> >> >>> fix something, it is very rare when they open a pull request and
>> rarer
>> >> >> that
>> >> >>> being merged within a week.
>> >> >>>
>> >> >>> No one is at fault here, but I feel we've collectively boiled the
>> frog.
>> >> >> I
>> >> >>> hope we can discuss this topic without anyone feeling attacked.
>> This
>> >> is
>> >> >>> just reflection.
>> >> >>>
>> >> >>> It should be easy to find, correct, and update docs. I work with
>> many
>> >> >>> projects and ours is by far the hardest to deal with. Something
>> has to
>> >> >>> give, and I'm apprehensive about fork lifting our old docs and
>> process
>> >> >> into
>> >> >>> the ASF.
>> >> >>>
>> >> >>> Personally, I really would love to use processes similar to what
>> other
>> >> >>> projects use for docs rather than being a snowflake. I desire less
>> >> >>> friction, explaining, bottlenecks, special instructions and gotchas.
>> >> >>>
>> >> >>> Do others feel this way? What options are on the table for doing
>> >> >>> documentation in the ASF?
>> >> >>>
>> >> >>> -A
>> >> >>>
>> >> >>
>> >>
>> >>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
I disagree that people should be making changes without that concern. I
hold this project to a high bar, I speak publicly about it, and as a result
the quality of the documentation has a bearing on my own career. I refuse
to allow poorly written documentation to continue, nor do I expect anyone
to go "fixing up" other people's poorly worded docs. If it doesn't meet
the bar, it needs to be fixed, and if it doesn't get fixed, it needs to be
reverted. We should treat this just like any other repository, and not
make an exception for it. If someone submitted code that was poorly
written and refused to fix it, I would expect you to revert that kind of
change.
Matt
On Sat, May 18, 2013 at 10:31 AM, Adrian Cole <ad...@gmail.com>wrote:
> Vetos only apply we are acting in a Review-Then-Commit or
> Commit-Then-Review mode, which doesn't apply to the outstanding vote
> on documentation. So, I think it is safe to say that in the case of
> docs, people shouldn't have fear of other people reverting their
> update, though clearly it is possible for any of us to commit
> something to undo the last doc update.
>
> I really hope we can establish a positive culture for docs that
> assumes change is for the better, and those making it have cause to do
> so. Those of us improving docs in response to users shouldn't have to
> worry about those updates being reverted without an extremely
> important justification. We should all focus on moving forward change
> vs how we can block them.
>
> -A
>
> http://www.apache.org/foundation/glossary.html#Veto
>
> On Sat, May 18, 2013 at 9:13 AM, Matt Stephenson <ma...@mattstep.net>
> wrote:
> > The bar is still high on doc changes. In this model, ignoring review
> > comments can result in your changes being reverted. It can be a much
> more
> > difficult experience for some documentarians.
> > On May 17, 2013 5:54 PM, "Everett Toews" <ev...@rackspace.com>
> > wrote:
> >
> >> I think this provides a better path to incremental doc improvement. It
> >> also lowers the barrier for people who only want to contribute doc.
> >>
> >> Everett
> >>
> >> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
> >>
> >> > I hear you, and I especially like moving the majority of the "thrashy
> >> docs"
> >> > to wikis.
> >> >
> >> > The intent here is to establish a procedure knowing we aren't staffed
> to
> >> do
> >> > reviews of every doc update in a central fashion. We all want good
> docs,
> >> > and we can't let best be the enemy of that. Though not necessarily
> the
> >> > case with you and others like Becca, folks contributing docs are
> doing so
> >> > in response to user problems or code shifts. Bad docs are important
> to
> >> fix
> >> > in a very timely fashion. We need folks with the right sort of
> pressures
> >> > to make the important fixes at the same time without precluding later
> >> > grammar, etc revisions by those who feel strongly about them. It is
> >> > possible that most of the fixes I mention fall into the "move to wiki"
> >> > category you mention.
> >> >
> >> > We have a couple things going on in this thread. One is how
> centralized
> >> > our docs are and the tech we use to maintain it. We'll surely have a
> lot
> >> > of opinions on that. Another is procedural: review before commit on
> docs
> >> > vs review after.
> >> >
> >> > Regardless, I believe it is better to trust those who contribute docs
> and
> >> > fixes first, and adjust later vs review before commit. This
> procedure is
> >> > very common across open source projects and also many companies. It
> does
> >> > carry the risks you mention about a possible bad doc getting in.
> >> >
> >> > Unless there's an overwhelming sense we won't have a majority buy-in
> for
> >> > that through this thread, I plan to call for a procedural vote to not
> >> > require review before commit on docs.
> >> >
> >> > -A
> >> >
> >> >
> >> >
> >> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <
> mattstep@mattstep.net
> >> >wrote:
> >> >
> >> >> IMHO, its hard to catch up on docs when it goes south. The process
> we
> >> have
> >> >> in my day job is this : doc is written/updated and sent for review,
> tech
> >> >> writer reviews and typically the feedback is that the change needs
> to be
> >> >> applied to other docs too. This helps expand the documentation.
> >> >>
> >> >> I believe that we have a good deal of docs that shouldn't be in the
> main
> >> >> doc tree for jclouds. The docs pertaining to contributing could
> easily
> >> be
> >> >> moved to the wiki.
> >> >>
> >> >> Its easy to look at the actions that created the docs as potential
> >> >> problems, but in my experience its the inaction. When people half
> ass
> >> >> their way through a doc, or a code change happens without a doc
> change
> >> due
> >> >> to laziness, things slip.
> >> >>
> >> >> Docs are more important than code, and they should be treated as
> such.
> >> I
> >> >> see many times review feedback isn't promptly dealt with and overall
> >> >> attention to detail is lost.
> >> >>
> >> >> I hope we come up with an easy process that doesnt lead to laziness.
> >> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com>
> wrote:
> >> >>
> >> >>> Hi, team.
> >> >>>
> >> >>> Since jclouds started, we've had many waves of doc efforts and
> >> approach.
> >> >> We
> >> >>> started with google wiki. It looked great and easy to update and
> >> control
> >> >>> access to. When we moved to GitHub we found access control absent
> >> which
> >> >>> led to Vijays hard work converting to markdown and hosting on github
> >> >> pages.
> >> >>> While some had patience to submit pull requests, our docs did rot.
> >> >> Becca
> >> >>> helped reface our website and spent a lot of effort to renovate
> select
> >> >>> documents and organized docs. She also removed the chance to
> >> completely
> >> >>> break the website due to accidentally breaking Jekyll. Meanwhile
> the
> >> >>> burden of fixing docs increased due to a combination of stricter
> >> >>> grammatical review and a perception that only Becca can approve
> things.
> >> >>> The commit log shows those tenacious enough can have content merged
> in
> >> a
> >> >>> couple weeks or so.
> >> >>>
> >> >>> Meanwhile, docs are often hard to find or broken. When I nudge
> someone
> >> >> to
> >> >>> fix something, it is very rare when they open a pull request and
> rarer
> >> >> that
> >> >>> being merged within a week.
> >> >>>
> >> >>> No one is at fault here, but I feel we've collectively boiled the
> frog.
> >> >> I
> >> >>> hope we can discuss this topic without anyone feeling attacked.
> This
> >> is
> >> >>> just reflection.
> >> >>>
> >> >>> It should be easy to find, correct, and update docs. I work with
> many
> >> >>> projects and ours is by far the hardest to deal with. Something
> has to
> >> >>> give, and I'm apprehensive about fork lifting our old docs and
> process
> >> >> into
> >> >>> the ASF.
> >> >>>
> >> >>> Personally, I really would love to use processes similar to what
> other
> >> >>> projects use for docs rather than being a snowflake. I desire less
> >> >>> friction, explaining, bottlenecks, special instructions and gotchas.
> >> >>>
> >> >>> Do others feel this way? What options are on the table for doing
> >> >>> documentation in the ASF?
> >> >>>
> >> >>> -A
> >> >>>
> >> >>
> >>
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Vetos only apply we are acting in a Review-Then-Commit or
Commit-Then-Review mode, which doesn't apply to the outstanding vote
on documentation. So, I think it is safe to say that in the case of
docs, people shouldn't have fear of other people reverting their
update, though clearly it is possible for any of us to commit
something to undo the last doc update.
I really hope we can establish a positive culture for docs that
assumes change is for the better, and those making it have cause to do
so. Those of us improving docs in response to users shouldn't have to
worry about those updates being reverted without an extremely
important justification. We should all focus on moving forward change
vs how we can block them.
-A
http://www.apache.org/foundation/glossary.html#Veto
On Sat, May 18, 2013 at 9:13 AM, Matt Stephenson <ma...@mattstep.net> wrote:
> The bar is still high on doc changes. In this model, ignoring review
> comments can result in your changes being reverted. It can be a much more
> difficult experience for some documentarians.
> On May 17, 2013 5:54 PM, "Everett Toews" <ev...@rackspace.com>
> wrote:
>
>> I think this provides a better path to incremental doc improvement. It
>> also lowers the barrier for people who only want to contribute doc.
>>
>> Everett
>>
>> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
>>
>> > I hear you, and I especially like moving the majority of the "thrashy
>> docs"
>> > to wikis.
>> >
>> > The intent here is to establish a procedure knowing we aren't staffed to
>> do
>> > reviews of every doc update in a central fashion. We all want good docs,
>> > and we can't let best be the enemy of that. Though not necessarily the
>> > case with you and others like Becca, folks contributing docs are doing so
>> > in response to user problems or code shifts. Bad docs are important to
>> fix
>> > in a very timely fashion. We need folks with the right sort of pressures
>> > to make the important fixes at the same time without precluding later
>> > grammar, etc revisions by those who feel strongly about them. It is
>> > possible that most of the fixes I mention fall into the "move to wiki"
>> > category you mention.
>> >
>> > We have a couple things going on in this thread. One is how centralized
>> > our docs are and the tech we use to maintain it. We'll surely have a lot
>> > of opinions on that. Another is procedural: review before commit on docs
>> > vs review after.
>> >
>> > Regardless, I believe it is better to trust those who contribute docs and
>> > fixes first, and adjust later vs review before commit. This procedure is
>> > very common across open source projects and also many companies. It does
>> > carry the risks you mention about a possible bad doc getting in.
>> >
>> > Unless there's an overwhelming sense we won't have a majority buy-in for
>> > that through this thread, I plan to call for a procedural vote to not
>> > require review before commit on docs.
>> >
>> > -A
>> >
>> >
>> >
>> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <mattstep@mattstep.net
>> >wrote:
>> >
>> >> IMHO, its hard to catch up on docs when it goes south. The process we
>> have
>> >> in my day job is this : doc is written/updated and sent for review, tech
>> >> writer reviews and typically the feedback is that the change needs to be
>> >> applied to other docs too. This helps expand the documentation.
>> >>
>> >> I believe that we have a good deal of docs that shouldn't be in the main
>> >> doc tree for jclouds. The docs pertaining to contributing could easily
>> be
>> >> moved to the wiki.
>> >>
>> >> Its easy to look at the actions that created the docs as potential
>> >> problems, but in my experience its the inaction. When people half ass
>> >> their way through a doc, or a code change happens without a doc change
>> due
>> >> to laziness, things slip.
>> >>
>> >> Docs are more important than code, and they should be treated as such.
>> I
>> >> see many times review feedback isn't promptly dealt with and overall
>> >> attention to detail is lost.
>> >>
>> >> I hope we come up with an easy process that doesnt lead to laziness.
>> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
>> >>
>> >>> Hi, team.
>> >>>
>> >>> Since jclouds started, we've had many waves of doc efforts and
>> approach.
>> >> We
>> >>> started with google wiki. It looked great and easy to update and
>> control
>> >>> access to. When we moved to GitHub we found access control absent
>> which
>> >>> led to Vijays hard work converting to markdown and hosting on github
>> >> pages.
>> >>> While some had patience to submit pull requests, our docs did rot.
>> >> Becca
>> >>> helped reface our website and spent a lot of effort to renovate select
>> >>> documents and organized docs. She also removed the chance to
>> completely
>> >>> break the website due to accidentally breaking Jekyll. Meanwhile the
>> >>> burden of fixing docs increased due to a combination of stricter
>> >>> grammatical review and a perception that only Becca can approve things.
>> >>> The commit log shows those tenacious enough can have content merged in
>> a
>> >>> couple weeks or so.
>> >>>
>> >>> Meanwhile, docs are often hard to find or broken. When I nudge someone
>> >> to
>> >>> fix something, it is very rare when they open a pull request and rarer
>> >> that
>> >>> being merged within a week.
>> >>>
>> >>> No one is at fault here, but I feel we've collectively boiled the frog.
>> >> I
>> >>> hope we can discuss this topic without anyone feeling attacked. This
>> is
>> >>> just reflection.
>> >>>
>> >>> It should be easy to find, correct, and update docs. I work with many
>> >>> projects and ours is by far the hardest to deal with. Something has to
>> >>> give, and I'm apprehensive about fork lifting our old docs and process
>> >> into
>> >>> the ASF.
>> >>>
>> >>> Personally, I really would love to use processes similar to what other
>> >>> projects use for docs rather than being a snowflake. I desire less
>> >>> friction, explaining, bottlenecks, special instructions and gotchas.
>> >>>
>> >>> Do others feel this way? What options are on the table for doing
>> >>> documentation in the ASF?
>> >>>
>> >>> -A
>> >>>
>> >>
>>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
The bar is still high on doc changes. In this model, ignoring review
comments can result in your changes being reverted. It can be a much more
difficult experience for some documentarians.
On May 17, 2013 5:54 PM, "Everett Toews" <ev...@rackspace.com>
wrote:
> I think this provides a better path to incremental doc improvement. It
> also lowers the barrier for people who only want to contribute doc.
>
> Everett
>
> On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
>
> > I hear you, and I especially like moving the majority of the "thrashy
> docs"
> > to wikis.
> >
> > The intent here is to establish a procedure knowing we aren't staffed to
> do
> > reviews of every doc update in a central fashion. We all want good docs,
> > and we can't let best be the enemy of that. Though not necessarily the
> > case with you and others like Becca, folks contributing docs are doing so
> > in response to user problems or code shifts. Bad docs are important to
> fix
> > in a very timely fashion. We need folks with the right sort of pressures
> > to make the important fixes at the same time without precluding later
> > grammar, etc revisions by those who feel strongly about them. It is
> > possible that most of the fixes I mention fall into the "move to wiki"
> > category you mention.
> >
> > We have a couple things going on in this thread. One is how centralized
> > our docs are and the tech we use to maintain it. We'll surely have a lot
> > of opinions on that. Another is procedural: review before commit on docs
> > vs review after.
> >
> > Regardless, I believe it is better to trust those who contribute docs and
> > fixes first, and adjust later vs review before commit. This procedure is
> > very common across open source projects and also many companies. It does
> > carry the risks you mention about a possible bad doc getting in.
> >
> > Unless there's an overwhelming sense we won't have a majority buy-in for
> > that through this thread, I plan to call for a procedural vote to not
> > require review before commit on docs.
> >
> > -A
> >
> >
> >
> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <mattstep@mattstep.net
> >wrote:
> >
> >> IMHO, its hard to catch up on docs when it goes south. The process we
> have
> >> in my day job is this : doc is written/updated and sent for review, tech
> >> writer reviews and typically the feedback is that the change needs to be
> >> applied to other docs too. This helps expand the documentation.
> >>
> >> I believe that we have a good deal of docs that shouldn't be in the main
> >> doc tree for jclouds. The docs pertaining to contributing could easily
> be
> >> moved to the wiki.
> >>
> >> Its easy to look at the actions that created the docs as potential
> >> problems, but in my experience its the inaction. When people half ass
> >> their way through a doc, or a code change happens without a doc change
> due
> >> to laziness, things slip.
> >>
> >> Docs are more important than code, and they should be treated as such.
> I
> >> see many times review feedback isn't promptly dealt with and overall
> >> attention to detail is lost.
> >>
> >> I hope we come up with an easy process that doesnt lead to laziness.
> >> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
> >>
> >>> Hi, team.
> >>>
> >>> Since jclouds started, we've had many waves of doc efforts and
> approach.
> >> We
> >>> started with google wiki. It looked great and easy to update and
> control
> >>> access to. When we moved to GitHub we found access control absent
> which
> >>> led to Vijays hard work converting to markdown and hosting on github
> >> pages.
> >>> While some had patience to submit pull requests, our docs did rot.
> >> Becca
> >>> helped reface our website and spent a lot of effort to renovate select
> >>> documents and organized docs. She also removed the chance to
> completely
> >>> break the website due to accidentally breaking Jekyll. Meanwhile the
> >>> burden of fixing docs increased due to a combination of stricter
> >>> grammatical review and a perception that only Becca can approve things.
> >>> The commit log shows those tenacious enough can have content merged in
> a
> >>> couple weeks or so.
> >>>
> >>> Meanwhile, docs are often hard to find or broken. When I nudge someone
> >> to
> >>> fix something, it is very rare when they open a pull request and rarer
> >> that
> >>> being merged within a week.
> >>>
> >>> No one is at fault here, but I feel we've collectively boiled the frog.
> >> I
> >>> hope we can discuss this topic without anyone feeling attacked. This
> is
> >>> just reflection.
> >>>
> >>> It should be easy to find, correct, and update docs. I work with many
> >>> projects and ours is by far the hardest to deal with. Something has to
> >>> give, and I'm apprehensive about fork lifting our old docs and process
> >> into
> >>> the ASF.
> >>>
> >>> Personally, I really would love to use processes similar to what other
> >>> projects use for docs rather than being a snowflake. I desire less
> >>> friction, explaining, bottlenecks, special instructions and gotchas.
> >>>
> >>> Do others feel this way? What options are on the table for doing
> >>> documentation in the ASF?
> >>>
> >>> -A
> >>>
> >>
>
>
Re: Documentation and what's next
Posted by Everett Toews <ev...@RACKSPACE.COM>.
I think this provides a better path to incremental doc improvement. It also lowers the barrier for people who only want to contribute doc.
Everett
On May 17, 2013, at 11:32 AM, Adrian Cole wrote:
> I hear you, and I especially like moving the majority of the "thrashy docs"
> to wikis.
>
> The intent here is to establish a procedure knowing we aren't staffed to do
> reviews of every doc update in a central fashion. We all want good docs,
> and we can't let best be the enemy of that. Though not necessarily the
> case with you and others like Becca, folks contributing docs are doing so
> in response to user problems or code shifts. Bad docs are important to fix
> in a very timely fashion. We need folks with the right sort of pressures
> to make the important fixes at the same time without precluding later
> grammar, etc revisions by those who feel strongly about them. It is
> possible that most of the fixes I mention fall into the "move to wiki"
> category you mention.
>
> We have a couple things going on in this thread. One is how centralized
> our docs are and the tech we use to maintain it. We'll surely have a lot
> of opinions on that. Another is procedural: review before commit on docs
> vs review after.
>
> Regardless, I believe it is better to trust those who contribute docs and
> fixes first, and adjust later vs review before commit. This procedure is
> very common across open source projects and also many companies. It does
> carry the risks you mention about a possible bad doc getting in.
>
> Unless there's an overwhelming sense we won't have a majority buy-in for
> that through this thread, I plan to call for a procedural vote to not
> require review before commit on docs.
>
> -A
>
>
>
> On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <ma...@mattstep.net>wrote:
>
>> IMHO, its hard to catch up on docs when it goes south. The process we have
>> in my day job is this : doc is written/updated and sent for review, tech
>> writer reviews and typically the feedback is that the change needs to be
>> applied to other docs too. This helps expand the documentation.
>>
>> I believe that we have a good deal of docs that shouldn't be in the main
>> doc tree for jclouds. The docs pertaining to contributing could easily be
>> moved to the wiki.
>>
>> Its easy to look at the actions that created the docs as potential
>> problems, but in my experience its the inaction. When people half ass
>> their way through a doc, or a code change happens without a doc change due
>> to laziness, things slip.
>>
>> Docs are more important than code, and they should be treated as such. I
>> see many times review feedback isn't promptly dealt with and overall
>> attention to detail is lost.
>>
>> I hope we come up with an easy process that doesnt lead to laziness.
>> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
>>
>>> Hi, team.
>>>
>>> Since jclouds started, we've had many waves of doc efforts and approach.
>> We
>>> started with google wiki. It looked great and easy to update and control
>>> access to. When we moved to GitHub we found access control absent which
>>> led to Vijays hard work converting to markdown and hosting on github
>> pages.
>>> While some had patience to submit pull requests, our docs did rot.
>> Becca
>>> helped reface our website and spent a lot of effort to renovate select
>>> documents and organized docs. She also removed the chance to completely
>>> break the website due to accidentally breaking Jekyll. Meanwhile the
>>> burden of fixing docs increased due to a combination of stricter
>>> grammatical review and a perception that only Becca can approve things.
>>> The commit log shows those tenacious enough can have content merged in a
>>> couple weeks or so.
>>>
>>> Meanwhile, docs are often hard to find or broken. When I nudge someone
>> to
>>> fix something, it is very rare when they open a pull request and rarer
>> that
>>> being merged within a week.
>>>
>>> No one is at fault here, but I feel we've collectively boiled the frog.
>> I
>>> hope we can discuss this topic without anyone feeling attacked. This is
>>> just reflection.
>>>
>>> It should be easy to find, correct, and update docs. I work with many
>>> projects and ours is by far the hardest to deal with. Something has to
>>> give, and I'm apprehensive about fork lifting our old docs and process
>> into
>>> the ASF.
>>>
>>> Personally, I really would love to use processes similar to what other
>>> projects use for docs rather than being a snowflake. I desire less
>>> friction, explaining, bottlenecks, special instructions and gotchas.
>>>
>>> Do others feel this way? What options are on the table for doing
>>> documentation in the ASF?
>>>
>>> -A
>>>
>>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
called! http://markmail.org/thread/qna7nssfxhgsupb4
(hopefully no typos this time)
On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <ad...@gmail.com> wrote:
> I don't think we have an issue on spammers. Contributor doesn't imply
> anonymous. I'll call the vote on C-T-R for code.
>
> http://www.apache.org/foundation/glossary.html#Contributor
>
> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <ma...@mattstep.net> wrote:
>> For the wiki : we need a way to deal with malicious updates. I don't want
>> spammers making changes.
>>
>> Call the vote, I say we switch across the board.
>>
>>
>> On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <ad...@gmail.com>wrote:
>>
>>> I think the main clarification in docs is that you don't need to wait
>>> for someone to +1 your updates before merging them. While we continue
>>> to use jekyll, it probably still makes sense to use pull requests for
>>> doc updates to jclouds.github.com as implicit syntax goofs can break
>>> the whole site. It also underscores that Contributors (not just
>>> Committers) can update docs on the wiki without asking.
>>>
>>> Your other question is about code change, basically do we follow
>>> Review-Then-Commit or Commit-Then-Review? In this case, such a
>>> decision would only apply to Committers as Contributors can't commit
>>> directly anyway. Personally, I'm fine with Commit-Then-Review and
>>> don't mind calling a vote on that.
>>>
>>> Cheers,
>>> -A
>>>
>>> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <ma...@mattstep.net>
>>> wrote:
>>> > What does this change? Does this just remove the +1'ing from another
>>> > committer for committer contributed docs?
>>> >
>>> > How is this different from the regular jclouds repos?
>>> >
>>> > Should we move to this across the board? I've got a ton of work to do
>>> > post-I/O and would benefit from post-review in the google labs project.
>>> >
>>> > Matt
>>> >
>>> >
>>> >
>>> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <adrian.f.cole@gmail.com
>>> >wrote:
>>> >
>>> >> At any rate, the vote applies to Contributors who will have already read
>>> >> the docs you refer to and possibly even this mail thread.
>>> >>
>>> >> The doc updates you refer to are valuable especially to the
>>> non-initiated,
>>> >> potential contributor. Having a clear message will hasten the
>>> >> bootstrapping of new contributors over time, so I definitely see value
>>> in
>>> >> being transparent about what we aspire towards or hold as good examples
>>> wrt
>>> >> docs.
>>> >>
>>> >> -A
>>> >>
>>> >> On Friday, May 17, 2013, Andrew Phillips wrote:
>>> >>
>>> >> > That said, I personally don't believe adding more rules and guidelines
>>> >> >> will help increase activity on docs, or encourage folks to write
>>> more or
>>> >> >> update old
>>> >> >>
>>> >> >
>>> >> > Fully agree, and apologies if that came across as "more rules and
>>> >> > guidelines please" ;-) To me, this could be as simple as "look at that
>>> >> > getting started guide over there as a good example" or remembering to
>>> ask
>>> >> > "that's a cool new feature in that PR, how about an example at
>>> >> > jclouds-examples" to show how to use it?
>>> >> >
>>> >> > The goal definititely should be to make it *easier* and *encouraged*
>>> to
>>> >> > keep our docs in good shape, not *harder*, as you said at the
>>> beginning
>>> >> of
>>> >> > this thread.
>>> >> >
>>> >> > ap
>>> >> >
>>> >>
>>>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
yeah good point.
On Fri, May 17, 2013 at 1:10 PM, Matt Stephenson <ma...@mattstep.net> wrote:
> As PMC members that is.
>
>
> On Fri, May 17, 2013 at 1:09 PM, Matt Stephenson <ma...@mattstep.net>wrote:
>
>> So as contributors we have the authority to make this call. I'm cool with
>> that.
>>
>>
>> On Fri, May 17, 2013 at 1:06 PM, Adrian Cole <ad...@gmail.com>wrote:
>>
>>> I think systems like our wiki could provide for updates by groups
>>> besides committers to the repo. For example, we already have
>>> Contributors in the Jira project; I've added a couple Jeremys and a
>>> Zach as Contributors as they meet the glossary def imho.
>>>
>>>
>>> https://issues.apache.org/jira/plugins/servlet/project-config/JCLOUDS/roles
>>>
>>> It would be another decision, if we chose to act more formally about
>>> who are Contributors (ex. a strict vote for each person like we do for
>>> Committers). Personally, I think it is ok to add based on the
>>> guidelines and correct if we find that doesn't work. What do you
>>> think?
>>>
>>> -A
>>>
>>> http://www.apache.org/foundation/glossary.html#Contributor
>>>
>>> On Fri, May 17, 2013 at 12:56 PM, Matt Stephenson <ma...@mattstep.net>
>>> wrote:
>>> > At this point we have no contributors then, and we'll need to vote them
>>> in,
>>> > correct?
>>> >
>>> >
>>> > On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <adrian.f.cole@gmail.com
>>> >wrote:
>>> >
>>> >> I don't think we have an issue on spammers. Contributor doesn't imply
>>> >> anonymous. I'll call the vote on C-T-R for code.
>>> >>
>>> >> http://www.apache.org/foundation/glossary.html#Contributor
>>> >>
>>> >> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <
>>> mattstep@mattstep.net>
>>> >> wrote:
>>> >> > For the wiki : we need a way to deal with malicious updates. I don't
>>> >> want
>>> >> > spammers making changes.
>>> >> >
>>> >> > Call the vote, I say we switch across the board.
>>> >> >
>>> >> >
>>> >> > On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <
>>> adrian.f.cole@gmail.com
>>> >> >wrote:
>>> >> >
>>> >> >> I think the main clarification in docs is that you don't need to
>>> wait
>>> >> >> for someone to +1 your updates before merging them. While we
>>> continue
>>> >> >> to use jekyll, it probably still makes sense to use pull requests
>>> for
>>> >> >> doc updates to jclouds.github.com as implicit syntax goofs can
>>> break
>>> >> >> the whole site. It also underscores that Contributors (not just
>>> >> >> Committers) can update docs on the wiki without asking.
>>> >> >>
>>> >> >> Your other question is about code change, basically do we follow
>>> >> >> Review-Then-Commit or Commit-Then-Review? In this case, such a
>>> >> >> decision would only apply to Committers as Contributors can't commit
>>> >> >> directly anyway. Personally, I'm fine with Commit-Then-Review and
>>> >> >> don't mind calling a vote on that.
>>> >> >>
>>> >> >> Cheers,
>>> >> >> -A
>>> >> >>
>>> >> >> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <
>>> >> mattstep@mattstep.net>
>>> >> >> wrote:
>>> >> >> > What does this change? Does this just remove the +1'ing from
>>> another
>>> >> >> > committer for committer contributed docs?
>>> >> >> >
>>> >> >> > How is this different from the regular jclouds repos?
>>> >> >> >
>>> >> >> > Should we move to this across the board? I've got a ton of work
>>> to do
>>> >> >> > post-I/O and would benefit from post-review in the google labs
>>> >> project.
>>> >> >> >
>>> >> >> > Matt
>>> >> >> >
>>> >> >> >
>>> >> >> >
>>> >> >> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <
>>> >> adrian.f.cole@gmail.com
>>> >> >> >wrote:
>>> >> >> >
>>> >> >> >> At any rate, the vote applies to Contributors who will have
>>> already
>>> >> read
>>> >> >> >> the docs you refer to and possibly even this mail thread.
>>> >> >> >>
>>> >> >> >> The doc updates you refer to are valuable especially to the
>>> >> >> non-initiated,
>>> >> >> >> potential contributor. Having a clear message will hasten the
>>> >> >> >> bootstrapping of new contributors over time, so I definitely see
>>> >> value
>>> >> >> in
>>> >> >> >> being transparent about what we aspire towards or hold as good
>>> >> examples
>>> >> >> wrt
>>> >> >> >> docs.
>>> >> >> >>
>>> >> >> >> -A
>>> >> >> >>
>>> >> >> >> On Friday, May 17, 2013, Andrew Phillips wrote:
>>> >> >> >>
>>> >> >> >> > That said, I personally don't believe adding more rules and
>>> >> guidelines
>>> >> >> >> >> will help increase activity on docs, or encourage folks to
>>> write
>>> >> >> more or
>>> >> >> >> >> update old
>>> >> >> >> >>
>>> >> >> >> >
>>> >> >> >> > Fully agree, and apologies if that came across as "more rules
>>> and
>>> >> >> >> > guidelines please" ;-) To me, this could be as simple as "look
>>> at
>>> >> that
>>> >> >> >> > getting started guide over there as a good example" or
>>> remembering
>>> >> to
>>> >> >> ask
>>> >> >> >> > "that's a cool new feature in that PR, how about an example at
>>> >> >> >> > jclouds-examples" to show how to use it?
>>> >> >> >> >
>>> >> >> >> > The goal definititely should be to make it *easier* and
>>> >> *encouraged*
>>> >> >> to
>>> >> >> >> > keep our docs in good shape, not *harder*, as you said at the
>>> >> >> beginning
>>> >> >> >> of
>>> >> >> >> > this thread.
>>> >> >> >> >
>>> >> >> >> > ap
>>> >> >> >> >
>>> >> >> >>
>>> >> >>
>>> >>
>>>
>>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
As PMC members that is.
On Fri, May 17, 2013 at 1:09 PM, Matt Stephenson <ma...@mattstep.net>wrote:
> So as contributors we have the authority to make this call. I'm cool with
> that.
>
>
> On Fri, May 17, 2013 at 1:06 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> I think systems like our wiki could provide for updates by groups
>> besides committers to the repo. For example, we already have
>> Contributors in the Jira project; I've added a couple Jeremys and a
>> Zach as Contributors as they meet the glossary def imho.
>>
>>
>> https://issues.apache.org/jira/plugins/servlet/project-config/JCLOUDS/roles
>>
>> It would be another decision, if we chose to act more formally about
>> who are Contributors (ex. a strict vote for each person like we do for
>> Committers). Personally, I think it is ok to add based on the
>> guidelines and correct if we find that doesn't work. What do you
>> think?
>>
>> -A
>>
>> http://www.apache.org/foundation/glossary.html#Contributor
>>
>> On Fri, May 17, 2013 at 12:56 PM, Matt Stephenson <ma...@mattstep.net>
>> wrote:
>> > At this point we have no contributors then, and we'll need to vote them
>> in,
>> > correct?
>> >
>> >
>> > On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <adrian.f.cole@gmail.com
>> >wrote:
>> >
>> >> I don't think we have an issue on spammers. Contributor doesn't imply
>> >> anonymous. I'll call the vote on C-T-R for code.
>> >>
>> >> http://www.apache.org/foundation/glossary.html#Contributor
>> >>
>> >> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <
>> mattstep@mattstep.net>
>> >> wrote:
>> >> > For the wiki : we need a way to deal with malicious updates. I don't
>> >> want
>> >> > spammers making changes.
>> >> >
>> >> > Call the vote, I say we switch across the board.
>> >> >
>> >> >
>> >> > On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <
>> adrian.f.cole@gmail.com
>> >> >wrote:
>> >> >
>> >> >> I think the main clarification in docs is that you don't need to
>> wait
>> >> >> for someone to +1 your updates before merging them. While we
>> continue
>> >> >> to use jekyll, it probably still makes sense to use pull requests
>> for
>> >> >> doc updates to jclouds.github.com as implicit syntax goofs can
>> break
>> >> >> the whole site. It also underscores that Contributors (not just
>> >> >> Committers) can update docs on the wiki without asking.
>> >> >>
>> >> >> Your other question is about code change, basically do we follow
>> >> >> Review-Then-Commit or Commit-Then-Review? In this case, such a
>> >> >> decision would only apply to Committers as Contributors can't commit
>> >> >> directly anyway. Personally, I'm fine with Commit-Then-Review and
>> >> >> don't mind calling a vote on that.
>> >> >>
>> >> >> Cheers,
>> >> >> -A
>> >> >>
>> >> >> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <
>> >> mattstep@mattstep.net>
>> >> >> wrote:
>> >> >> > What does this change? Does this just remove the +1'ing from
>> another
>> >> >> > committer for committer contributed docs?
>> >> >> >
>> >> >> > How is this different from the regular jclouds repos?
>> >> >> >
>> >> >> > Should we move to this across the board? I've got a ton of work
>> to do
>> >> >> > post-I/O and would benefit from post-review in the google labs
>> >> project.
>> >> >> >
>> >> >> > Matt
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <
>> >> adrian.f.cole@gmail.com
>> >> >> >wrote:
>> >> >> >
>> >> >> >> At any rate, the vote applies to Contributors who will have
>> already
>> >> read
>> >> >> >> the docs you refer to and possibly even this mail thread.
>> >> >> >>
>> >> >> >> The doc updates you refer to are valuable especially to the
>> >> >> non-initiated,
>> >> >> >> potential contributor. Having a clear message will hasten the
>> >> >> >> bootstrapping of new contributors over time, so I definitely see
>> >> value
>> >> >> in
>> >> >> >> being transparent about what we aspire towards or hold as good
>> >> examples
>> >> >> wrt
>> >> >> >> docs.
>> >> >> >>
>> >> >> >> -A
>> >> >> >>
>> >> >> >> On Friday, May 17, 2013, Andrew Phillips wrote:
>> >> >> >>
>> >> >> >> > That said, I personally don't believe adding more rules and
>> >> guidelines
>> >> >> >> >> will help increase activity on docs, or encourage folks to
>> write
>> >> >> more or
>> >> >> >> >> update old
>> >> >> >> >>
>> >> >> >> >
>> >> >> >> > Fully agree, and apologies if that came across as "more rules
>> and
>> >> >> >> > guidelines please" ;-) To me, this could be as simple as "look
>> at
>> >> that
>> >> >> >> > getting started guide over there as a good example" or
>> remembering
>> >> to
>> >> >> ask
>> >> >> >> > "that's a cool new feature in that PR, how about an example at
>> >> >> >> > jclouds-examples" to show how to use it?
>> >> >> >> >
>> >> >> >> > The goal definititely should be to make it *easier* and
>> >> *encouraged*
>> >> >> to
>> >> >> >> > keep our docs in good shape, not *harder*, as you said at the
>> >> >> beginning
>> >> >> >> of
>> >> >> >> > this thread.
>> >> >> >> >
>> >> >> >> > ap
>> >> >> >> >
>> >> >> >>
>> >> >>
>> >>
>>
>
>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
So as contributors we have the authority to make this call. I'm cool with
that.
On Fri, May 17, 2013 at 1:06 PM, Adrian Cole <ad...@gmail.com>wrote:
> I think systems like our wiki could provide for updates by groups
> besides committers to the repo. For example, we already have
> Contributors in the Jira project; I've added a couple Jeremys and a
> Zach as Contributors as they meet the glossary def imho.
>
> https://issues.apache.org/jira/plugins/servlet/project-config/JCLOUDS/roles
>
> It would be another decision, if we chose to act more formally about
> who are Contributors (ex. a strict vote for each person like we do for
> Committers). Personally, I think it is ok to add based on the
> guidelines and correct if we find that doesn't work. What do you
> think?
>
> -A
>
> http://www.apache.org/foundation/glossary.html#Contributor
>
> On Fri, May 17, 2013 at 12:56 PM, Matt Stephenson <ma...@mattstep.net>
> wrote:
> > At this point we have no contributors then, and we'll need to vote them
> in,
> > correct?
> >
> >
> > On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
> >
> >> I don't think we have an issue on spammers. Contributor doesn't imply
> >> anonymous. I'll call the vote on C-T-R for code.
> >>
> >> http://www.apache.org/foundation/glossary.html#Contributor
> >>
> >> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <
> mattstep@mattstep.net>
> >> wrote:
> >> > For the wiki : we need a way to deal with malicious updates. I don't
> >> want
> >> > spammers making changes.
> >> >
> >> > Call the vote, I say we switch across the board.
> >> >
> >> >
> >> > On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <
> adrian.f.cole@gmail.com
> >> >wrote:
> >> >
> >> >> I think the main clarification in docs is that you don't need to wait
> >> >> for someone to +1 your updates before merging them. While we
> continue
> >> >> to use jekyll, it probably still makes sense to use pull requests for
> >> >> doc updates to jclouds.github.com as implicit syntax goofs can break
> >> >> the whole site. It also underscores that Contributors (not just
> >> >> Committers) can update docs on the wiki without asking.
> >> >>
> >> >> Your other question is about code change, basically do we follow
> >> >> Review-Then-Commit or Commit-Then-Review? In this case, such a
> >> >> decision would only apply to Committers as Contributors can't commit
> >> >> directly anyway. Personally, I'm fine with Commit-Then-Review and
> >> >> don't mind calling a vote on that.
> >> >>
> >> >> Cheers,
> >> >> -A
> >> >>
> >> >> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <
> >> mattstep@mattstep.net>
> >> >> wrote:
> >> >> > What does this change? Does this just remove the +1'ing from
> another
> >> >> > committer for committer contributed docs?
> >> >> >
> >> >> > How is this different from the regular jclouds repos?
> >> >> >
> >> >> > Should we move to this across the board? I've got a ton of work
> to do
> >> >> > post-I/O and would benefit from post-review in the google labs
> >> project.
> >> >> >
> >> >> > Matt
> >> >> >
> >> >> >
> >> >> >
> >> >> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <
> >> adrian.f.cole@gmail.com
> >> >> >wrote:
> >> >> >
> >> >> >> At any rate, the vote applies to Contributors who will have
> already
> >> read
> >> >> >> the docs you refer to and possibly even this mail thread.
> >> >> >>
> >> >> >> The doc updates you refer to are valuable especially to the
> >> >> non-initiated,
> >> >> >> potential contributor. Having a clear message will hasten the
> >> >> >> bootstrapping of new contributors over time, so I definitely see
> >> value
> >> >> in
> >> >> >> being transparent about what we aspire towards or hold as good
> >> examples
> >> >> wrt
> >> >> >> docs.
> >> >> >>
> >> >> >> -A
> >> >> >>
> >> >> >> On Friday, May 17, 2013, Andrew Phillips wrote:
> >> >> >>
> >> >> >> > That said, I personally don't believe adding more rules and
> >> guidelines
> >> >> >> >> will help increase activity on docs, or encourage folks to
> write
> >> >> more or
> >> >> >> >> update old
> >> >> >> >>
> >> >> >> >
> >> >> >> > Fully agree, and apologies if that came across as "more rules
> and
> >> >> >> > guidelines please" ;-) To me, this could be as simple as "look
> at
> >> that
> >> >> >> > getting started guide over there as a good example" or
> remembering
> >> to
> >> >> ask
> >> >> >> > "that's a cool new feature in that PR, how about an example at
> >> >> >> > jclouds-examples" to show how to use it?
> >> >> >> >
> >> >> >> > The goal definititely should be to make it *easier* and
> >> *encouraged*
> >> >> to
> >> >> >> > keep our docs in good shape, not *harder*, as you said at the
> >> >> beginning
> >> >> >> of
> >> >> >> > this thread.
> >> >> >> >
> >> >> >> > ap
> >> >> >> >
> >> >> >>
> >> >>
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
I think systems like our wiki could provide for updates by groups
besides committers to the repo. For example, we already have
Contributors in the Jira project; I've added a couple Jeremys and a
Zach as Contributors as they meet the glossary def imho.
https://issues.apache.org/jira/plugins/servlet/project-config/JCLOUDS/roles
It would be another decision, if we chose to act more formally about
who are Contributors (ex. a strict vote for each person like we do for
Committers). Personally, I think it is ok to add based on the
guidelines and correct if we find that doesn't work. What do you
think?
-A
http://www.apache.org/foundation/glossary.html#Contributor
On Fri, May 17, 2013 at 12:56 PM, Matt Stephenson <ma...@mattstep.net> wrote:
> At this point we have no contributors then, and we'll need to vote them in,
> correct?
>
>
> On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> I don't think we have an issue on spammers. Contributor doesn't imply
>> anonymous. I'll call the vote on C-T-R for code.
>>
>> http://www.apache.org/foundation/glossary.html#Contributor
>>
>> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <ma...@mattstep.net>
>> wrote:
>> > For the wiki : we need a way to deal with malicious updates. I don't
>> want
>> > spammers making changes.
>> >
>> > Call the vote, I say we switch across the board.
>> >
>> >
>> > On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <adrian.f.cole@gmail.com
>> >wrote:
>> >
>> >> I think the main clarification in docs is that you don't need to wait
>> >> for someone to +1 your updates before merging them. While we continue
>> >> to use jekyll, it probably still makes sense to use pull requests for
>> >> doc updates to jclouds.github.com as implicit syntax goofs can break
>> >> the whole site. It also underscores that Contributors (not just
>> >> Committers) can update docs on the wiki without asking.
>> >>
>> >> Your other question is about code change, basically do we follow
>> >> Review-Then-Commit or Commit-Then-Review? In this case, such a
>> >> decision would only apply to Committers as Contributors can't commit
>> >> directly anyway. Personally, I'm fine with Commit-Then-Review and
>> >> don't mind calling a vote on that.
>> >>
>> >> Cheers,
>> >> -A
>> >>
>> >> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <
>> mattstep@mattstep.net>
>> >> wrote:
>> >> > What does this change? Does this just remove the +1'ing from another
>> >> > committer for committer contributed docs?
>> >> >
>> >> > How is this different from the regular jclouds repos?
>> >> >
>> >> > Should we move to this across the board? I've got a ton of work to do
>> >> > post-I/O and would benefit from post-review in the google labs
>> project.
>> >> >
>> >> > Matt
>> >> >
>> >> >
>> >> >
>> >> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <
>> adrian.f.cole@gmail.com
>> >> >wrote:
>> >> >
>> >> >> At any rate, the vote applies to Contributors who will have already
>> read
>> >> >> the docs you refer to and possibly even this mail thread.
>> >> >>
>> >> >> The doc updates you refer to are valuable especially to the
>> >> non-initiated,
>> >> >> potential contributor. Having a clear message will hasten the
>> >> >> bootstrapping of new contributors over time, so I definitely see
>> value
>> >> in
>> >> >> being transparent about what we aspire towards or hold as good
>> examples
>> >> wrt
>> >> >> docs.
>> >> >>
>> >> >> -A
>> >> >>
>> >> >> On Friday, May 17, 2013, Andrew Phillips wrote:
>> >> >>
>> >> >> > That said, I personally don't believe adding more rules and
>> guidelines
>> >> >> >> will help increase activity on docs, or encourage folks to write
>> >> more or
>> >> >> >> update old
>> >> >> >>
>> >> >> >
>> >> >> > Fully agree, and apologies if that came across as "more rules and
>> >> >> > guidelines please" ;-) To me, this could be as simple as "look at
>> that
>> >> >> > getting started guide over there as a good example" or remembering
>> to
>> >> ask
>> >> >> > "that's a cool new feature in that PR, how about an example at
>> >> >> > jclouds-examples" to show how to use it?
>> >> >> >
>> >> >> > The goal definititely should be to make it *easier* and
>> *encouraged*
>> >> to
>> >> >> > keep our docs in good shape, not *harder*, as you said at the
>> >> beginning
>> >> >> of
>> >> >> > this thread.
>> >> >> >
>> >> >> > ap
>> >> >> >
>> >> >>
>> >>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
At this point we have no contributors then, and we'll need to vote them in,
correct?
On Fri, May 17, 2013 at 12:54 PM, Adrian Cole <ad...@gmail.com>wrote:
> I don't think we have an issue on spammers. Contributor doesn't imply
> anonymous. I'll call the vote on C-T-R for code.
>
> http://www.apache.org/foundation/glossary.html#Contributor
>
> On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <ma...@mattstep.net>
> wrote:
> > For the wiki : we need a way to deal with malicious updates. I don't
> want
> > spammers making changes.
> >
> > Call the vote, I say we switch across the board.
> >
> >
> > On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
> >
> >> I think the main clarification in docs is that you don't need to wait
> >> for someone to +1 your updates before merging them. While we continue
> >> to use jekyll, it probably still makes sense to use pull requests for
> >> doc updates to jclouds.github.com as implicit syntax goofs can break
> >> the whole site. It also underscores that Contributors (not just
> >> Committers) can update docs on the wiki without asking.
> >>
> >> Your other question is about code change, basically do we follow
> >> Review-Then-Commit or Commit-Then-Review? In this case, such a
> >> decision would only apply to Committers as Contributors can't commit
> >> directly anyway. Personally, I'm fine with Commit-Then-Review and
> >> don't mind calling a vote on that.
> >>
> >> Cheers,
> >> -A
> >>
> >> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <
> mattstep@mattstep.net>
> >> wrote:
> >> > What does this change? Does this just remove the +1'ing from another
> >> > committer for committer contributed docs?
> >> >
> >> > How is this different from the regular jclouds repos?
> >> >
> >> > Should we move to this across the board? I've got a ton of work to do
> >> > post-I/O and would benefit from post-review in the google labs
> project.
> >> >
> >> > Matt
> >> >
> >> >
> >> >
> >> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <
> adrian.f.cole@gmail.com
> >> >wrote:
> >> >
> >> >> At any rate, the vote applies to Contributors who will have already
> read
> >> >> the docs you refer to and possibly even this mail thread.
> >> >>
> >> >> The doc updates you refer to are valuable especially to the
> >> non-initiated,
> >> >> potential contributor. Having a clear message will hasten the
> >> >> bootstrapping of new contributors over time, so I definitely see
> value
> >> in
> >> >> being transparent about what we aspire towards or hold as good
> examples
> >> wrt
> >> >> docs.
> >> >>
> >> >> -A
> >> >>
> >> >> On Friday, May 17, 2013, Andrew Phillips wrote:
> >> >>
> >> >> > That said, I personally don't believe adding more rules and
> guidelines
> >> >> >> will help increase activity on docs, or encourage folks to write
> >> more or
> >> >> >> update old
> >> >> >>
> >> >> >
> >> >> > Fully agree, and apologies if that came across as "more rules and
> >> >> > guidelines please" ;-) To me, this could be as simple as "look at
> that
> >> >> > getting started guide over there as a good example" or remembering
> to
> >> ask
> >> >> > "that's a cool new feature in that PR, how about an example at
> >> >> > jclouds-examples" to show how to use it?
> >> >> >
> >> >> > The goal definititely should be to make it *easier* and
> *encouraged*
> >> to
> >> >> > keep our docs in good shape, not *harder*, as you said at the
> >> beginning
> >> >> of
> >> >> > this thread.
> >> >> >
> >> >> > ap
> >> >> >
> >> >>
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
I don't think we have an issue on spammers. Contributor doesn't imply
anonymous. I'll call the vote on C-T-R for code.
http://www.apache.org/foundation/glossary.html#Contributor
On Fri, May 17, 2013 at 12:52 PM, Matt Stephenson <ma...@mattstep.net> wrote:
> For the wiki : we need a way to deal with malicious updates. I don't want
> spammers making changes.
>
> Call the vote, I say we switch across the board.
>
>
> On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> I think the main clarification in docs is that you don't need to wait
>> for someone to +1 your updates before merging them. While we continue
>> to use jekyll, it probably still makes sense to use pull requests for
>> doc updates to jclouds.github.com as implicit syntax goofs can break
>> the whole site. It also underscores that Contributors (not just
>> Committers) can update docs on the wiki without asking.
>>
>> Your other question is about code change, basically do we follow
>> Review-Then-Commit or Commit-Then-Review? In this case, such a
>> decision would only apply to Committers as Contributors can't commit
>> directly anyway. Personally, I'm fine with Commit-Then-Review and
>> don't mind calling a vote on that.
>>
>> Cheers,
>> -A
>>
>> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <ma...@mattstep.net>
>> wrote:
>> > What does this change? Does this just remove the +1'ing from another
>> > committer for committer contributed docs?
>> >
>> > How is this different from the regular jclouds repos?
>> >
>> > Should we move to this across the board? I've got a ton of work to do
>> > post-I/O and would benefit from post-review in the google labs project.
>> >
>> > Matt
>> >
>> >
>> >
>> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <adrian.f.cole@gmail.com
>> >wrote:
>> >
>> >> At any rate, the vote applies to Contributors who will have already read
>> >> the docs you refer to and possibly even this mail thread.
>> >>
>> >> The doc updates you refer to are valuable especially to the
>> non-initiated,
>> >> potential contributor. Having a clear message will hasten the
>> >> bootstrapping of new contributors over time, so I definitely see value
>> in
>> >> being transparent about what we aspire towards or hold as good examples
>> wrt
>> >> docs.
>> >>
>> >> -A
>> >>
>> >> On Friday, May 17, 2013, Andrew Phillips wrote:
>> >>
>> >> > That said, I personally don't believe adding more rules and guidelines
>> >> >> will help increase activity on docs, or encourage folks to write
>> more or
>> >> >> update old
>> >> >>
>> >> >
>> >> > Fully agree, and apologies if that came across as "more rules and
>> >> > guidelines please" ;-) To me, this could be as simple as "look at that
>> >> > getting started guide over there as a good example" or remembering to
>> ask
>> >> > "that's a cool new feature in that PR, how about an example at
>> >> > jclouds-examples" to show how to use it?
>> >> >
>> >> > The goal definititely should be to make it *easier* and *encouraged*
>> to
>> >> > keep our docs in good shape, not *harder*, as you said at the
>> beginning
>> >> of
>> >> > this thread.
>> >> >
>> >> > ap
>> >> >
>> >>
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
For the wiki : we need a way to deal with malicious updates. I don't want
spammers making changes.
Call the vote, I say we switch across the board.
On Fri, May 17, 2013 at 12:49 PM, Adrian Cole <ad...@gmail.com>wrote:
> I think the main clarification in docs is that you don't need to wait
> for someone to +1 your updates before merging them. While we continue
> to use jekyll, it probably still makes sense to use pull requests for
> doc updates to jclouds.github.com as implicit syntax goofs can break
> the whole site. It also underscores that Contributors (not just
> Committers) can update docs on the wiki without asking.
>
> Your other question is about code change, basically do we follow
> Review-Then-Commit or Commit-Then-Review? In this case, such a
> decision would only apply to Committers as Contributors can't commit
> directly anyway. Personally, I'm fine with Commit-Then-Review and
> don't mind calling a vote on that.
>
> Cheers,
> -A
>
> On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <ma...@mattstep.net>
> wrote:
> > What does this change? Does this just remove the +1'ing from another
> > committer for committer contributed docs?
> >
> > How is this different from the regular jclouds repos?
> >
> > Should we move to this across the board? I've got a ton of work to do
> > post-I/O and would benefit from post-review in the google labs project.
> >
> > Matt
> >
> >
> >
> > On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
> >
> >> At any rate, the vote applies to Contributors who will have already read
> >> the docs you refer to and possibly even this mail thread.
> >>
> >> The doc updates you refer to are valuable especially to the
> non-initiated,
> >> potential contributor. Having a clear message will hasten the
> >> bootstrapping of new contributors over time, so I definitely see value
> in
> >> being transparent about what we aspire towards or hold as good examples
> wrt
> >> docs.
> >>
> >> -A
> >>
> >> On Friday, May 17, 2013, Andrew Phillips wrote:
> >>
> >> > That said, I personally don't believe adding more rules and guidelines
> >> >> will help increase activity on docs, or encourage folks to write
> more or
> >> >> update old
> >> >>
> >> >
> >> > Fully agree, and apologies if that came across as "more rules and
> >> > guidelines please" ;-) To me, this could be as simple as "look at that
> >> > getting started guide over there as a good example" or remembering to
> ask
> >> > "that's a cool new feature in that PR, how about an example at
> >> > jclouds-examples" to show how to use it?
> >> >
> >> > The goal definititely should be to make it *easier* and *encouraged*
> to
> >> > keep our docs in good shape, not *harder*, as you said at the
> beginning
> >> of
> >> > this thread.
> >> >
> >> > ap
> >> >
> >>
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
I think the main clarification in docs is that you don't need to wait
for someone to +1 your updates before merging them. While we continue
to use jekyll, it probably still makes sense to use pull requests for
doc updates to jclouds.github.com as implicit syntax goofs can break
the whole site. It also underscores that Contributors (not just
Committers) can update docs on the wiki without asking.
Your other question is about code change, basically do we follow
Review-Then-Commit or Commit-Then-Review? In this case, such a
decision would only apply to Committers as Contributors can't commit
directly anyway. Personally, I'm fine with Commit-Then-Review and
don't mind calling a vote on that.
Cheers,
-A
On Fri, May 17, 2013 at 12:40 PM, Matt Stephenson <ma...@mattstep.net> wrote:
> What does this change? Does this just remove the +1'ing from another
> committer for committer contributed docs?
>
> How is this different from the regular jclouds repos?
>
> Should we move to this across the board? I've got a ton of work to do
> post-I/O and would benefit from post-review in the google labs project.
>
> Matt
>
>
>
> On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <ad...@gmail.com>wrote:
>
>> At any rate, the vote applies to Contributors who will have already read
>> the docs you refer to and possibly even this mail thread.
>>
>> The doc updates you refer to are valuable especially to the non-initiated,
>> potential contributor. Having a clear message will hasten the
>> bootstrapping of new contributors over time, so I definitely see value in
>> being transparent about what we aspire towards or hold as good examples wrt
>> docs.
>>
>> -A
>>
>> On Friday, May 17, 2013, Andrew Phillips wrote:
>>
>> > That said, I personally don't believe adding more rules and guidelines
>> >> will help increase activity on docs, or encourage folks to write more or
>> >> update old
>> >>
>> >
>> > Fully agree, and apologies if that came across as "more rules and
>> > guidelines please" ;-) To me, this could be as simple as "look at that
>> > getting started guide over there as a good example" or remembering to ask
>> > "that's a cool new feature in that PR, how about an example at
>> > jclouds-examples" to show how to use it?
>> >
>> > The goal definititely should be to make it *easier* and *encouraged* to
>> > keep our docs in good shape, not *harder*, as you said at the beginning
>> of
>> > this thread.
>> >
>> > ap
>> >
>>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
What does this change? Does this just remove the +1'ing from another
committer for committer contributed docs?
How is this different from the regular jclouds repos?
Should we move to this across the board? I've got a ton of work to do
post-I/O and would benefit from post-review in the google labs project.
Matt
On Fri, May 17, 2013 at 12:14 PM, Adrian Cole <ad...@gmail.com>wrote:
> At any rate, the vote applies to Contributors who will have already read
> the docs you refer to and possibly even this mail thread.
>
> The doc updates you refer to are valuable especially to the non-initiated,
> potential contributor. Having a clear message will hasten the
> bootstrapping of new contributors over time, so I definitely see value in
> being transparent about what we aspire towards or hold as good examples wrt
> docs.
>
> -A
>
> On Friday, May 17, 2013, Andrew Phillips wrote:
>
> > That said, I personally don't believe adding more rules and guidelines
> >> will help increase activity on docs, or encourage folks to write more or
> >> update old
> >>
> >
> > Fully agree, and apologies if that came across as "more rules and
> > guidelines please" ;-) To me, this could be as simple as "look at that
> > getting started guide over there as a good example" or remembering to ask
> > "that's a cool new feature in that PR, how about an example at
> > jclouds-examples" to show how to use it?
> >
> > The goal definititely should be to make it *easier* and *encouraged* to
> > keep our docs in good shape, not *harder*, as you said at the beginning
> of
> > this thread.
> >
> > ap
> >
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
At any rate, the vote applies to Contributors who will have already read
the docs you refer to and possibly even this mail thread.
The doc updates you refer to are valuable especially to the non-initiated,
potential contributor. Having a clear message will hasten the
bootstrapping of new contributors over time, so I definitely see value in
being transparent about what we aspire towards or hold as good examples wrt
docs.
-A
On Friday, May 17, 2013, Andrew Phillips wrote:
> That said, I personally don't believe adding more rules and guidelines
>> will help increase activity on docs, or encourage folks to write more or
>> update old
>>
>
> Fully agree, and apologies if that came across as "more rules and
> guidelines please" ;-) To me, this could be as simple as "look at that
> getting started guide over there as a good example" or remembering to ask
> "that's a cool new feature in that PR, how about an example at
> jclouds-examples" to show how to use it?
>
> The goal definititely should be to make it *easier* and *encouraged* to
> keep our docs in good shape, not *harder*, as you said at the beginning of
> this thread.
>
> ap
>
Re: Documentation and what's next
Posted by Andrew Phillips <ap...@qrmedia.com>.
> That said, I personally don't believe adding more rules and
> guidelines will help increase activity on docs, or encourage folks
> to write more or update old
Fully agree, and apologies if that came across as "more rules and
guidelines please" ;-) To me, this could be as simple as "look at that
getting started guide over there as a good example" or remembering to
ask "that's a cool new feature in that PR, how about an example at
jclouds-examples" to show how to use it?
The goal definititely should be to make it *easier* and *encouraged*
to keep our docs in good shape, not *harder*, as you said at the
beginning of this thread.
ap
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
:) I think the meta points are interesting, and could be added to a "how to
write good docs" doc or embedded into the contributing to docs doc. That
said, I personally don't believe adding more rules and guidelines will help
increase activity on docs, or encourage folks to write more or update old
ones. This in mind, I'm still in favor of giving contributors freedom to
update docs.
On Fri, May 17, 2013 at 11:20 AM, Andrew Phillips <ap...@qrmedia.com>wrote:
> I'm certainly in favour of any changes we can make to ensure our
> documentation is more up-to-date. If we feel the review process for docs is
> currently a barrier to that, then anything we can do to make it quicker and
> easier is worth considering, such as the vote Adrian just proposed.
>
> There are two other points that I think could also help:
>
> 1. Provide more guidance on *how* to write documentation, i.e. what level
> of detail, what kind of style etc. to provide, even if that's simply "go
> look at this doc for an example".
>
> We currently have comprehensive instructions [1] for how to *submit*
> documentation, but can do more, I think, to guide people in *what* to
> write. With that kind of guidance, whatever review process we end up with
> would hopefully be quicker, too.
>
> 2. Make it clearer what the community's expectations are with regard to
> providing *and updating* documentation for code and features changes.
>
> I don't know if we'd feel comfortable with an expectation such as "if you
> contribute a provider, you should contribute a Getting Started guide too"
> or "if you provide a new feature, you should think about updating an
> example to showcase that feature", but I think that could at least help
> combat out-of-dateness.
>
> Regards
>
> ap
>
> [1] http://www.jclouds.org/**documentation/devguides/**
> contributing-to-documentation/<http://www.jclouds.org/documentation/devguides/contributing-to-documentation/>
>
Re: Documentation and what's next
Posted by Andrew Phillips <ap...@qrmedia.com>.
I'm certainly in favour of any changes we can make to ensure our
documentation is more up-to-date. If we feel the review process for
docs is currently a barrier to that, then anything we can do to make
it quicker and easier is worth considering, such as the vote Adrian
just proposed.
There are two other points that I think could also help:
1. Provide more guidance on *how* to write documentation, i.e. what
level of detail, what kind of style etc. to provide, even if that's
simply "go look at this doc for an example".
We currently have comprehensive instructions [1] for how to *submit*
documentation, but can do more, I think, to guide people in *what* to
write. With that kind of guidance, whatever review process we end up
with would hopefully be quicker, too.
2. Make it clearer what the community's expectations are with regard
to providing *and updating* documentation for code and features changes.
I don't know if we'd feel comfortable with an expectation such as "if
you contribute a provider, you should contribute a Getting Started
guide too" or "if you provide a new feature, you should think about
updating an example to showcase that feature", but I think that could
at least help combat out-of-dateness.
Regards
ap
[1]
http://www.jclouds.org/documentation/devguides/contributing-to-documentation/
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
Opinion noted. Note that the vote I called for does not require people to
address comments, so I won't be surprised if you -1 it :)
http://apache.markmail.org/thread/ntiq2opo4a5ifcfa
On Fri, May 17, 2013 at 10:28 AM, Matt Stephenson <ma...@apache.org>wrote:
> I don't believe people take feedback seriously in a post-commit-review
> world. Especially for docs. If we move to this model we will probably be
> leaning on those that care about the grammar to watch commits and fix
> things for people instead of people fixing it themselves.
>
> I'm comfortable with this change if we're also comfortable with reverting
> commits when comments on commits aren't addressed. This is usually taken
> as very offensive, but that is the only real powerful feedback mechanism a
> reviewer has in a post-commit-review process.
>
> Matt
>
>
> On Fri, May 17, 2013 at 9:32 AM, Adrian Cole <adrian.f.cole@gmail.com
> >wrote:
>
> > I hear you, and I especially like moving the majority of the "thrashy
> docs"
> > to wikis.
> >
> > The intent here is to establish a procedure knowing we aren't staffed to
> do
> > reviews of every doc update in a central fashion. We all want good docs,
> > and we can't let best be the enemy of that. Though not necessarily the
> > case with you and others like Becca, folks contributing docs are doing so
> > in response to user problems or code shifts. Bad docs are important to
> fix
> > in a very timely fashion. We need folks with the right sort of pressures
> > to make the important fixes at the same time without precluding later
> > grammar, etc revisions by those who feel strongly about them. It is
> > possible that most of the fixes I mention fall into the "move to wiki"
> > category you mention.
> >
> > We have a couple things going on in this thread. One is how centralized
> > our docs are and the tech we use to maintain it. We'll surely have a lot
> > of opinions on that. Another is procedural: review before commit on docs
> > vs review after.
> >
> > Regardless, I believe it is better to trust those who contribute docs and
> > fixes first, and adjust later vs review before commit. This procedure is
> > very common across open source projects and also many companies. It does
> > carry the risks you mention about a possible bad doc getting in.
> >
> > Unless there's an overwhelming sense we won't have a majority buy-in for
> > that through this thread, I plan to call for a procedural vote to not
> > require review before commit on docs.
> >
> > -A
> >
> >
> >
> > On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <mattstep@mattstep.net
> > >wrote:
> >
> > > IMHO, its hard to catch up on docs when it goes south. The process we
> > have
> > > in my day job is this : doc is written/updated and sent for review,
> tech
> > > writer reviews and typically the feedback is that the change needs to
> be
> > > applied to other docs too. This helps expand the documentation.
> > >
> > > I believe that we have a good deal of docs that shouldn't be in the
> main
> > > doc tree for jclouds. The docs pertaining to contributing could easily
> > be
> > > moved to the wiki.
> > >
> > > Its easy to look at the actions that created the docs as potential
> > > problems, but in my experience its the inaction. When people half ass
> > > their way through a doc, or a code change happens without a doc change
> > due
> > > to laziness, things slip.
> > >
> > > Docs are more important than code, and they should be treated as such.
> I
> > > see many times review feedback isn't promptly dealt with and overall
> > > attention to detail is lost.
> > >
> > > I hope we come up with an easy process that doesnt lead to laziness.
> > > On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com>
> wrote:
> > >
> > > > Hi, team.
> > > >
> > > > Since jclouds started, we've had many waves of doc efforts and
> > approach.
> > > We
> > > > started with google wiki. It looked great and easy to update and
> > control
> > > > access to. When we moved to GitHub we found access control absent
> > which
> > > > led to Vijays hard work converting to markdown and hosting on github
> > > pages.
> > > > While some had patience to submit pull requests, our docs did rot.
> > > Becca
> > > > helped reface our website and spent a lot of effort to renovate
> select
> > > > documents and organized docs. She also removed the chance to
> > completely
> > > > break the website due to accidentally breaking Jekyll. Meanwhile the
> > > > burden of fixing docs increased due to a combination of stricter
> > > > grammatical review and a perception that only Becca can approve
> things.
> > > > The commit log shows those tenacious enough can have content merged
> > in a
> > > > couple weeks or so.
> > > >
> > > > Meanwhile, docs are often hard to find or broken. When I nudge
> someone
> > > to
> > > > fix something, it is very rare when they open a pull request and
> rarer
> > > that
> > > > being merged within a week.
> > > >
> > > > No one is at fault here, but I feel we've collectively boiled the
> frog.
> > > I
> > > > hope we can discuss this topic without anyone feeling attacked. This
> > is
> > > > just reflection.
> > > >
> > > > It should be easy to find, correct, and update docs. I work with
> many
> > > > projects and ours is by far the hardest to deal with. Something has
> to
> > > > give, and I'm apprehensive about fork lifting our old docs and
> process
> > > into
> > > > the ASF.
> > > >
> > > > Personally, I really would love to use processes similar to what
> other
> > > > projects use for docs rather than being a snowflake. I desire less
> > > > friction, explaining, bottlenecks, special instructions and gotchas.
> > > >
> > > > Do others feel this way? What options are on the table for doing
> > > > documentation in the ASF?
> > > >
> > > > -A
> > > >
> > >
> >
>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@apache.org>.
I don't believe people take feedback seriously in a post-commit-review
world. Especially for docs. If we move to this model we will probably be
leaning on those that care about the grammar to watch commits and fix
things for people instead of people fixing it themselves.
I'm comfortable with this change if we're also comfortable with reverting
commits when comments on commits aren't addressed. This is usually taken
as very offensive, but that is the only real powerful feedback mechanism a
reviewer has in a post-commit-review process.
Matt
On Fri, May 17, 2013 at 9:32 AM, Adrian Cole <ad...@gmail.com>wrote:
> I hear you, and I especially like moving the majority of the "thrashy docs"
> to wikis.
>
> The intent here is to establish a procedure knowing we aren't staffed to do
> reviews of every doc update in a central fashion. We all want good docs,
> and we can't let best be the enemy of that. Though not necessarily the
> case with you and others like Becca, folks contributing docs are doing so
> in response to user problems or code shifts. Bad docs are important to fix
> in a very timely fashion. We need folks with the right sort of pressures
> to make the important fixes at the same time without precluding later
> grammar, etc revisions by those who feel strongly about them. It is
> possible that most of the fixes I mention fall into the "move to wiki"
> category you mention.
>
> We have a couple things going on in this thread. One is how centralized
> our docs are and the tech we use to maintain it. We'll surely have a lot
> of opinions on that. Another is procedural: review before commit on docs
> vs review after.
>
> Regardless, I believe it is better to trust those who contribute docs and
> fixes first, and adjust later vs review before commit. This procedure is
> very common across open source projects and also many companies. It does
> carry the risks you mention about a possible bad doc getting in.
>
> Unless there's an overwhelming sense we won't have a majority buy-in for
> that through this thread, I plan to call for a procedural vote to not
> require review before commit on docs.
>
> -A
>
>
>
> On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <mattstep@mattstep.net
> >wrote:
>
> > IMHO, its hard to catch up on docs when it goes south. The process we
> have
> > in my day job is this : doc is written/updated and sent for review, tech
> > writer reviews and typically the feedback is that the change needs to be
> > applied to other docs too. This helps expand the documentation.
> >
> > I believe that we have a good deal of docs that shouldn't be in the main
> > doc tree for jclouds. The docs pertaining to contributing could easily
> be
> > moved to the wiki.
> >
> > Its easy to look at the actions that created the docs as potential
> > problems, but in my experience its the inaction. When people half ass
> > their way through a doc, or a code change happens without a doc change
> due
> > to laziness, things slip.
> >
> > Docs are more important than code, and they should be treated as such. I
> > see many times review feedback isn't promptly dealt with and overall
> > attention to detail is lost.
> >
> > I hope we come up with an easy process that doesnt lead to laziness.
> > On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
> >
> > > Hi, team.
> > >
> > > Since jclouds started, we've had many waves of doc efforts and
> approach.
> > We
> > > started with google wiki. It looked great and easy to update and
> control
> > > access to. When we moved to GitHub we found access control absent
> which
> > > led to Vijays hard work converting to markdown and hosting on github
> > pages.
> > > While some had patience to submit pull requests, our docs did rot.
> > Becca
> > > helped reface our website and spent a lot of effort to renovate select
> > > documents and organized docs. She also removed the chance to
> completely
> > > break the website due to accidentally breaking Jekyll. Meanwhile the
> > > burden of fixing docs increased due to a combination of stricter
> > > grammatical review and a perception that only Becca can approve things.
> > > The commit log shows those tenacious enough can have content merged
> in a
> > > couple weeks or so.
> > >
> > > Meanwhile, docs are often hard to find or broken. When I nudge someone
> > to
> > > fix something, it is very rare when they open a pull request and rarer
> > that
> > > being merged within a week.
> > >
> > > No one is at fault here, but I feel we've collectively boiled the frog.
> > I
> > > hope we can discuss this topic without anyone feeling attacked. This
> is
> > > just reflection.
> > >
> > > It should be easy to find, correct, and update docs. I work with many
> > > projects and ours is by far the hardest to deal with. Something has to
> > > give, and I'm apprehensive about fork lifting our old docs and process
> > into
> > > the ASF.
> > >
> > > Personally, I really would love to use processes similar to what other
> > > projects use for docs rather than being a snowflake. I desire less
> > > friction, explaining, bottlenecks, special instructions and gotchas.
> > >
> > > Do others feel this way? What options are on the table for doing
> > > documentation in the ASF?
> > >
> > > -A
> > >
> >
>
Re: Documentation and what's next
Posted by Adrian Cole <ad...@gmail.com>.
I hear you, and I especially like moving the majority of the "thrashy docs"
to wikis.
The intent here is to establish a procedure knowing we aren't staffed to do
reviews of every doc update in a central fashion. We all want good docs,
and we can't let best be the enemy of that. Though not necessarily the
case with you and others like Becca, folks contributing docs are doing so
in response to user problems or code shifts. Bad docs are important to fix
in a very timely fashion. We need folks with the right sort of pressures
to make the important fixes at the same time without precluding later
grammar, etc revisions by those who feel strongly about them. It is
possible that most of the fixes I mention fall into the "move to wiki"
category you mention.
We have a couple things going on in this thread. One is how centralized
our docs are and the tech we use to maintain it. We'll surely have a lot
of opinions on that. Another is procedural: review before commit on docs
vs review after.
Regardless, I believe it is better to trust those who contribute docs and
fixes first, and adjust later vs review before commit. This procedure is
very common across open source projects and also many companies. It does
carry the risks you mention about a possible bad doc getting in.
Unless there's an overwhelming sense we won't have a majority buy-in for
that through this thread, I plan to call for a procedural vote to not
require review before commit on docs.
-A
On Fri, May 17, 2013 at 9:01 AM, Matt Stephenson <ma...@mattstep.net>wrote:
> IMHO, its hard to catch up on docs when it goes south. The process we have
> in my day job is this : doc is written/updated and sent for review, tech
> writer reviews and typically the feedback is that the change needs to be
> applied to other docs too. This helps expand the documentation.
>
> I believe that we have a good deal of docs that shouldn't be in the main
> doc tree for jclouds. The docs pertaining to contributing could easily be
> moved to the wiki.
>
> Its easy to look at the actions that created the docs as potential
> problems, but in my experience its the inaction. When people half ass
> their way through a doc, or a code change happens without a doc change due
> to laziness, things slip.
>
> Docs are more important than code, and they should be treated as such. I
> see many times review feedback isn't promptly dealt with and overall
> attention to detail is lost.
>
> I hope we come up with an easy process that doesnt lead to laziness.
> On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
>
> > Hi, team.
> >
> > Since jclouds started, we've had many waves of doc efforts and approach.
> We
> > started with google wiki. It looked great and easy to update and control
> > access to. When we moved to GitHub we found access control absent which
> > led to Vijays hard work converting to markdown and hosting on github
> pages.
> > While some had patience to submit pull requests, our docs did rot.
> Becca
> > helped reface our website and spent a lot of effort to renovate select
> > documents and organized docs. She also removed the chance to completely
> > break the website due to accidentally breaking Jekyll. Meanwhile the
> > burden of fixing docs increased due to a combination of stricter
> > grammatical review and a perception that only Becca can approve things.
> > The commit log shows those tenacious enough can have content merged in a
> > couple weeks or so.
> >
> > Meanwhile, docs are often hard to find or broken. When I nudge someone
> to
> > fix something, it is very rare when they open a pull request and rarer
> that
> > being merged within a week.
> >
> > No one is at fault here, but I feel we've collectively boiled the frog.
> I
> > hope we can discuss this topic without anyone feeling attacked. This is
> > just reflection.
> >
> > It should be easy to find, correct, and update docs. I work with many
> > projects and ours is by far the hardest to deal with. Something has to
> > give, and I'm apprehensive about fork lifting our old docs and process
> into
> > the ASF.
> >
> > Personally, I really would love to use processes similar to what other
> > projects use for docs rather than being a snowflake. I desire less
> > friction, explaining, bottlenecks, special instructions and gotchas.
> >
> > Do others feel this way? What options are on the table for doing
> > documentation in the ASF?
> >
> > -A
> >
>
Re: Documentation and what's next
Posted by Matt Stephenson <ma...@mattstep.net>.
IMHO, its hard to catch up on docs when it goes south. The process we have
in my day job is this : doc is written/updated and sent for review, tech
writer reviews and typically the feedback is that the change needs to be
applied to other docs too. This helps expand the documentation.
I believe that we have a good deal of docs that shouldn't be in the main
doc tree for jclouds. The docs pertaining to contributing could easily be
moved to the wiki.
Its easy to look at the actions that created the docs as potential
problems, but in my experience its the inaction. When people half ass
their way through a doc, or a code change happens without a doc change due
to laziness, things slip.
Docs are more important than code, and they should be treated as such. I
see many times review feedback isn't promptly dealt with and overall
attention to detail is lost.
I hope we come up with an easy process that doesnt lead to laziness.
On May 17, 2013 8:08 AM, "Adrian Cole" <ad...@gmail.com> wrote:
> Hi, team.
>
> Since jclouds started, we've had many waves of doc efforts and approach. We
> started with google wiki. It looked great and easy to update and control
> access to. When we moved to GitHub we found access control absent which
> led to Vijays hard work converting to markdown and hosting on github pages.
> While some had patience to submit pull requests, our docs did rot. Becca
> helped reface our website and spent a lot of effort to renovate select
> documents and organized docs. She also removed the chance to completely
> break the website due to accidentally breaking Jekyll. Meanwhile the
> burden of fixing docs increased due to a combination of stricter
> grammatical review and a perception that only Becca can approve things.
> The commit log shows those tenacious enough can have content merged in a
> couple weeks or so.
>
> Meanwhile, docs are often hard to find or broken. When I nudge someone to
> fix something, it is very rare when they open a pull request and rarer that
> being merged within a week.
>
> No one is at fault here, but I feel we've collectively boiled the frog. I
> hope we can discuss this topic without anyone feeling attacked. This is
> just reflection.
>
> It should be easy to find, correct, and update docs. I work with many
> projects and ours is by far the hardest to deal with. Something has to
> give, and I'm apprehensive about fork lifting our old docs and process into
> the ASF.
>
> Personally, I really would love to use processes similar to what other
> projects use for docs rather than being a snowflake. I desire less
> friction, explaining, bottlenecks, special instructions and gotchas.
>
> Do others feel this way? What options are on the table for doing
> documentation in the ASF?
>
> -A
>