[Gluster-devel] Documentation expectations for 3.5 release

[Lalatendu Mohanty]

On 04/16/2014 03:39 AM, Jeff Darcy wrote:
>>> 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.
>> Ok.  Hadn't really thought of 3.5 as a "fix" for 3.4 bugs.  Kind of
>> thought 3.4.x series was for that.  So what you're saying is that
>> 3.5 isn't just about releasing new features, it's also a more stable/better
>> platform for people to run on?
> That is generally true of every new release.  Fixes are backported *if
> the benefit outweighs the risk* but are always present in the new release.
> Some bugs aren't so much fixed as made irrelevant by refactoring.  Some
> fixes have dependencies on other new code.  Whatever the reason, whether
> it's more about risk or more about effort, there will always be some fixes
> that don't go into older releases.
>
>>> 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.
>> If people have things they _need_ that are only in 3.5 then I can
>> definitely understand they're going to be unhappy with a delay.
>>
>> But won't they also be unhappy with a 3.5 release where the features
>> they want don't have docs?
> Sure they will.  The question is which kind of unhappiness will be
> worse for them, or for the project.  The answers are not simple.  I've
> seen reasonable arguments for both sides.  We need to do two things
> that will make our users happier; the only debate is about the order.

True, there can be reasonable arguments on both the sides. If you see 
the present situation, user docs for new features seems to be more 
important (IMO) for Gluster. I find it disturbing how users are 
struggling in community to use a feature, even if the feature is present 
in GlusterFS code.

How are we expecting the user will use a feature if example of basic cli 
commands are not available?

I had spent some time testing 3.5 betas. But could not test some of the 
new feature as there are no user documentation available on how to use 
them and I didn't have time to go through the code to figure out how to 
use a particular feature.
>> Put it this way... my thinking is that at the moment the "lack of docs
>> in Gluster 3.5" is a *developer* problem, not a user one.  If we
>> release 3.5 without (even basic) docs for *all* of the new features,
>> we've just promoted it to a user problem *as well as* a developer
>> problem.
> It's a developer problem *and* a user problem either way.
>
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel