Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-15 Thread John Mark Walker
Agreed. Let's push it out and bake in the doc process for the next release.

Justin - you are in charge of defining the release requirements for the
follow-up docs release.

Can we agree on this? Let's make this release available by tomorrow so
Vijay and I can talk about the just-released 3.5.

-JM
On Apr 15, 2014 1:58 PM, Jeff Darcy jda...@redhat.com wrote:

  Is there _actual pressure_ from a defined source (who I can speak to), or
  is it something such as we're really overdue already, etc?

 |
 That's setting the bar a bit high, don't you think?  Those of us at
 Summit have all had the dubious pleasure of telling users that the
 feature they asked about isn't available in a release yet.  Should we
 follow up that bad news by asking them to go out of their way to contact
 some random guy who's not there, or sign a statement spelling out
 exactly what effect lack of that feature had on their decision not to
 deploy GlusterFS?  Should you provide similar proof regarding your
 claims about lack of documentation?  Of course not.

 We all get that poor documentation hurts the project.  Some of us have
 even tried to do something about that.  Most of us also realize that
 releases dragging on too long *also* hurt the project in a variety of
 ways.  Having to maintain an active current-release branch in addition
 to master is a drag on development.  Users are ill served by being
 unable to get fixes for actual bugs in easily consumable form.  We're
 dealing with a tradeoff here, not something where one side gets to put
 on a white hat and jam the black hat on somebody else.

 I'm deliberately not taking a position on whether or not we should
 release with the documentation in its current state.  All I'm saying
 is that making inequitable demands of one another, or trying to
 portray one another as failing to appreciate users' needs, hurts
 the project even more than either poor documentation or late
 releases.  That's an issue on which I *am* willing to take a stand.

 ___
 Gluster-devel mailing list
 Gluster-devel@nongnu.org
 https://lists.nongnu.org/mailman/listinfo/gluster-devel

___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-15 Thread John Mark Walker

On Apr 15, 2014 5:36 PM, Justin Clift jus...@gluster.org wrote:

 On 15/04/2014, at 10:02 PM, John Mark Walker wrote: 
  Justin - you are in charge of defining the release requirements for the 
  follow-up docs release. 

 No.  I'd rather not be.

Ok. Someone will need to step up.


  Can we agree on this? Let's make this release available by tomorrow so 
  Vijay and I can talk about the just-released 3.5. 

 If that's what's needed, then go for it.  But I'm going to finish the 
 present stuff I'm working on, and then see what's needed after that.

OK. Thanks.

I want to see the dev team produce a plan for wrapping docs into each new 
feature. I don't want to go through this again.

-JM
___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-15 Thread John Mark Walker

On Apr 15, 2014 6:09 PM, Jeff Darcy jda...@redhat.com wrote:

 It's a developer problem *and* a user problem either way. 


Right. The most productive thing we can do right now is come up with a plan for 
future releases.

Because the expectations for docs were not set until the last minute, it's not 
really fair to mandate them at this point in the Dev cycle. But now that you 
know we're serious about it, there is an incentive to do it the right way from 
now on and bake docs into the release process. I interjected not because I 
thought we'd write all the docs immediately, but because I wanted to raise 
awareness of the problem. And make no mistake - it is a huge problem.

Right now, let's push this release with the understanding that we need to avoid 
this situation in the future. Getting adequate docs for releases is extremely 
important. Let's make sure we have them in place.

-JM
___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-15 Thread Joe Julian
Like I always say, I'm just a user. I'm happy when my input is considered but 
I'm not a developer so I know that my -1 doesn't really count.

I'm kind of surprised it's this hard and that in the week this has been 
discussed as a release requirement that it didn't just get done. Now we're 
saying that it can't get done in a reasonable amount of time so let's put it 
off while we start the development cycle for 3.6 and somehow more time can be 
made this time to go back and document as a 3.5.1 release than has in the past.

I agree documentation is a chore. You guys are brilliant and, as I do with my 
own challenges, want to move on to the next one. I understand that emotion. I 
also know that the longer it's put off the more you want to put it off. Just 
the idea of breaking your current train of thought to shift gears and go back 
to that thing you finished weeks ago is stressful and daunting. 

The only way I can do it is to bite the bullet and just do it. Get it over with 
so it's no longer dangling over your head. 

I hope you understand that I'm not adversarial about this. I have invested a 
lot of my own time in this project to and take pride in my involvement. I want 
this to be the best damn SDS in the industry and part of that is documentation. 
When people talk shit about Gluster the only thing I can't argue on merit is 
complaints about documentation. I want to be able to proudly tell people they 
are full of it when they complain.

The things I've documented in my blog came from scratch. I knew, at times, 
nothing at all about what I was writing when I started. I had to read code and 
test and debug. None of them took me more than three days and that's in my 
off-hours. 

Please get the documentation done. 

On April 15, 2014 2:02:00 PM PDT, John Mark Walker johnm...@johnmark.org 
wrote:
Agreed. Let's push it out and bake in the doc process for the next
release.

Justin - you are in charge of defining the release requirements for the
follow-up docs release.

Can we agree on this? Let's make this release available by tomorrow so
Vijay and I can talk about the just-released 3.5.

-JM
On Apr 15, 2014 1:58 PM, Jeff Darcy jda...@redhat.com wrote:

  Is there _actual pressure_ from a defined source (who I can speak
to), or
  is it something such as we're really overdue already, etc?

 |
 That's setting the bar a bit high, don't you think?  Those of us at
 Summit have all had the dubious pleasure of telling users that the
 feature they asked about isn't available in a release yet.  Should we
 follow up that bad news by asking them to go out of their way to
contact
 some random guy who's not there, or sign a statement spelling out
 exactly what effect lack of that feature had on their decision not to
 deploy GlusterFS?  Should you provide similar proof regarding your
 claims about lack of documentation?  Of course not.

 We all get that poor documentation hurts the project.  Some of us
have
 even tried to do something about that.  Most of us also realize that
 releases dragging on too long *also* hurt the project in a variety of
 ways.  Having to maintain an active current-release branch in
addition
 to master is a drag on development.  Users are ill served by being
 unable to get fixes for actual bugs in easily consumable form.  We're
 dealing with a tradeoff here, not something where one side gets to
put
 on a white hat and jam the black hat on somebody else.

 I'm deliberately not taking a position on whether or not we should
 release with the documentation in its current state.  All I'm saying
 is that making inequitable demands of one another, or trying to
 portray one another as failing to appreciate users' needs, hurts
 the project even more than either poor documentation or late
 releases.  That's an issue on which I *am* willing to take a stand.

 ___
 Gluster-devel mailing list
 Gluster-devel@nongnu.org
 https://lists.nongnu.org/mailman/listinfo/gluster-devel





___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-15 Thread Jeff Darcy
 Please get the documentation done.

+1 on that. It shouldn't even need to wait for a release. It shouldn't even 
have to wait for people to agonize over the wording, or fight with 
Markdown/AsciiDoc/whatever. Justin's a great communicator. So's Joe. 
Developers, explain what you've done to one of them, or to me, and we can turn 
that into basic documentation. (Sorry for volunteering you guys, but I'm a jerk 
that way.) Do it as soon as you've written the code, while it's still fresh in 
your mind, and we'll never have to go through any of *this* crap at the end of 
a release again.

___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-11 Thread Niels de Vos
On Thu, Apr 10, 2014 at 11:47:08PM +0530, Lalatendu Mohanty wrote:
 On 04/10/2014 11:20 PM, Justin Clift wrote:
 Note, the docs go in the /doc directory in the git repo, both 3.5 and
 master branches. ;)
 
 When submitting patches to gerrit, feel free to reuse the bug-
 branch that was used for the code submission, or even use the 3.5.0
 tracker bug (1049981).
 
 Here is the documentation about how to send documentation patch : 
 http://www.gluster.org/community/documentation/index.php/Submitting_Documentation_Patches

Lala and I have been busy filing bugs for all of the features that are 
listed in the email below as having missing documentation:
- https://bugzilla.redhat.com/showdependencytree.cgi?id=1049981

All the bugs that are *not* in POST or MODIFIED state need to file 
patches. The ones that are in POST could probably benefit from reviews 
in Gerrit (see the respective bug for details).

Note that these bugs need patches submitted against the release-3.5 
branch, as well as the master branch. We do not want documentation lost 
with future releases.

If you have any questions, please let us know by replying to this email, 
or talk to us in #gluster-dev on Freenode.

Thanks,
Niels


 
 + Justin
 
 On 10/04/2014, at 6:21 PM, Justin Clift wrote:
 Hi all,
 
 These are the features in Gluster 3.5 still needing documentation:
 
 * AFR CLI enhancements
 * Exposing Volume Capabilities - only if this made it in, which I can't 
 see atm
 * File Snapshots in GlusterFS
 * gfid-access
 * On-Wire Compression/Decompression
 * Preventing NFS restart on volume change
 * Quota Scalability
 * readdir-ahead
 * zerofill API for GlusterFS
 * Brick Failure Detection
 * Disk Encryption
 * Changelog based parallel geo-replication
 * Improved block device translator
 * Remove brick CLI change
 * RDMA-connection manager (RDMA-CM)
 * Support for NUFA translator
 * Distributed Geo-Replication
 
 These are the features added in Gluster 3.4, still needing documentation:
 
 * Write Once Read Many (WORM) volume
 * BD Xlator - Block Device translator
 * Duplicate Request Cache (DRC)
 * Server-Quorum
 * Libgfapi
 * Eager locking
 * oVirt 3.2 integration
 * qemu 1.3 - libgfapi integration
 * Access Control List - Version 3 support for Gluster NFS
 
 
 All of the required documentation is *end user focused*, which includes
 three parts:
 
 a) Description of what a feature does, so a user knows if it's something
 they'd want to use or try
 
 b) Exact steps on setting it up, and full list of parameters that can affect
 it.  For example:
 
   * CLI parameters (if it has them)
   * Volume options/parameters (if it has them)
   * Dependencies, (eg on other features, external programs,
 etc)
 
 c) A fully worked example.  Step by step commands with comments are optimal.
 
 A good way to start is by doing the setup/configuration for the feature in 
 your
 local environment, starting from a new, un-configured installation. Ensure 
 your
 terminal program has a lot of scroll back buffer available. :)
 
 After the environment is fully configured, cut-n-paste the scroll back 
 buffer
 into a text mode document editor somewhere (or an etherpad).  Then go 
 through
 it, removing everything except the needed commands and any useful output.
 
 Then go through it a 2nd time, adding line feeds and headings, spacing 
 things
 out visually for clarity, and adding comments to describe what's going on 
 and
 why it's being done.
 
 This becomes the c) in the list above.  With that in place, it's generally
 pretty straight forward to next make the b) part, and then finishing off 
 with
 a full feature description appropriate for end users (if it hasn't
 spontaneously come to mind already).
 
 The text format we're using is AsciiDoc.  Quick Reference here:
 
 http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
 
 :)
 
 Regards and best wishes,
 
 Justin Clift
 
 --
 Open Source and Standards @ Red Hat
 
 twitter.com/realjustinclift
 
 
 ___
 Gluster-devel mailing list
 Gluster-devel@nongnu.org
 https://lists.nongnu.org/mailman/listinfo/gluster-devel
 --
 Open Source and Standards @ Red Hat
 
 twitter.com/realjustinclift
 
 
 ___
 Gluster-devel mailing list
 Gluster-devel@nongnu.org
 https://lists.nongnu.org/mailman/listinfo/gluster-devel
 
 
 ___
 Gluster-devel mailing list
 Gluster-devel@nongnu.org
 https://lists.nongnu.org/mailman/listinfo/gluster-devel

-- 
Niels de Vos
Sr. Software Maintenance Engineer
Support Engineering Group
Red Hat Global Support Services

___
Gluster-devel mailing list
Gluster-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/gluster-devel


Re: [Gluster-devel] Documentation expectations for 3.5 release

2014-04-11 Thread John Mark Walker
Thank you, guys, for taking this on. The community will greatly benefit from 
this effort.

-JM


- Original Message -
 On Thu, Apr 10, 2014 at 11:47:08PM +0530, Lalatendu Mohanty wrote:
  On 04/10/2014 11:20 PM, Justin Clift wrote:
  Note, the docs go in the /doc directory in the git repo, both 3.5 and
  master branches. ;)
  
  When submitting patches to gerrit, feel free to reuse the bug-
  branch that was used for the code submission, or even use the 3.5.0
  tracker bug (1049981).
  
  Here is the documentation about how to send documentation patch :
  http://www.gluster.org/community/documentation/index.php/Submitting_Documentation_Patches
 
 Lala and I have been busy filing bugs for all of the features that are
 listed in the email below as having missing documentation:
 - https://bugzilla.redhat.com/showdependencytree.cgi?id=1049981
 
 All the bugs that are *not* in POST or MODIFIED state need to file
 patches. The ones that are in POST could probably benefit from reviews
 in Gerrit (see the respective bug for details).
 
 Note that these bugs need patches submitted against the release-3.5
 branch, as well as the master branch. We do not want documentation lost
 with future releases.
 
 If you have any questions, please let us know by replying to this email,
 or talk to us in #gluster-dev on Freenode.
 
 Thanks,
 Niels
 
 
  
  + Justin
  
  On 10/04/2014, at 6:21 PM, Justin Clift wrote:
  Hi all,
  
  These are the features in Gluster 3.5 still needing documentation:
  
  * AFR CLI enhancements
  * Exposing Volume Capabilities - only if this made it in, which I can't
  see atm
  * File Snapshots in GlusterFS
  * gfid-access
  * On-Wire Compression/Decompression
  * Preventing NFS restart on volume change
  * Quota Scalability
  * readdir-ahead
  * zerofill API for GlusterFS
  * Brick Failure Detection
  * Disk Encryption
  * Changelog based parallel geo-replication
  * Improved block device translator
  * Remove brick CLI change
  * RDMA-connection manager (RDMA-CM)
  * Support for NUFA translator
  * Distributed Geo-Replication
  
  These are the features added in Gluster 3.4, still needing documentation:
  
  * Write Once Read Many (WORM) volume
  * BD Xlator - Block Device translator
  * Duplicate Request Cache (DRC)
  * Server-Quorum
  * Libgfapi
  * Eager locking
  * oVirt 3.2 integration
  * qemu 1.3 - libgfapi integration
  * Access Control List - Version 3 support for Gluster NFS
  
  
  All of the required documentation is *end user focused*, which includes
  three parts:
  
  a) Description of what a feature does, so a user knows if it's something
  they'd want to use or try
  
  b) Exact steps on setting it up, and full list of parameters that can
  affect
  it.  For example:
  
* CLI parameters (if it has them)
* Volume options/parameters (if it has them)
* Dependencies, (eg on other features, external programs,
  etc)
  
  c) A fully worked example.  Step by step commands with comments are
  optimal.
  
  A good way to start is by doing the setup/configuration for the feature
  in your
  local environment, starting from a new, un-configured installation.
  Ensure your
  terminal program has a lot of scroll back buffer available. :)
  
  After the environment is fully configured, cut-n-paste the scroll back
  buffer
  into a text mode document editor somewhere (or an etherpad).  Then go
  through
  it, removing everything except the needed commands and any useful output.
  
  Then go through it a 2nd time, adding line feeds and headings, spacing
  things
  out visually for clarity, and adding comments to describe what's going on
  and
  why it's being done.
  
  This becomes the c) in the list above.  With that in place, it's
  generally
  pretty straight forward to next make the b) part, and then finishing off
  with
  a full feature description appropriate for end users (if it hasn't
  spontaneously come to mind already).
  
  The text format we're using is AsciiDoc.  Quick Reference here:
  
  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
  
  :)
  
  Regards and best wishes,
  
  Justin Clift
  
  --
  Open Source and Standards @ Red Hat
  
  twitter.com/realjustinclift
  
  
  ___
  Gluster-devel mailing list
  Gluster-devel@nongnu.org
  https://lists.nongnu.org/mailman/listinfo/gluster-devel
  --
  Open Source and Standards @ Red Hat
  
  twitter.com/realjustinclift
  
  
  ___
  Gluster-devel mailing list
  Gluster-devel@nongnu.org
  https://lists.nongnu.org/mailman/listinfo/gluster-devel
  
  
  ___
  Gluster-devel mailing list
  Gluster-devel@nongnu.org
  https://lists.nongnu.org/mailman/listinfo/gluster-devel
 
 --
 Niels de Vos
 Sr. Software Maintenance Engineer
 Support Engineering Group
 Red Hat Global Support Services
 
 ___