[Gluster-devel] Documentation expectations for 3.5 release

Joe Julian joe at julianfamily.org
Tue Apr 15 22:46:31 UTC 2014


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 <johnmark at 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" <jdarcy at 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 at nongnu.org
>> https://lists.nongnu.org/mailman/listinfo/gluster-devel
>>
>
>
>------------------------------------------------------------------------
>
>_______________________________________________
>Gluster-devel mailing list
>Gluster-devel at nongnu.org
>https://lists.nongnu.org/mailman/listinfo/gluster-devel

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20140415/aa95b91a/attachment-0001.html>


More information about the Gluster-devel mailing list