[Gluster-devel] Documentation expectations for 3.5 release

[Justin Clift]

On 15/04/2014, at 9:58 PM, Jeff Darcy 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?

Not seeing why really. 

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

That doesn't make sense to me.


> 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?


> 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?

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.

?

+ Justin

--
Open Source and Standards @ Red Hat

twitter.com/realjustinclift