[Gluster-users] Working but some issues

[Melkor Lord]

On Mon, Mar 16, 2015 at 5:14 AM, Joe Julian <joe at julianfamily.org> wrote:

>
> I'll just address this one point in this email because it's such an
> important one. This is not just an open-source project because some
> company's developing a product and lets you have it for free, this is an
> open-source *project*. We, the members of the community, are as
> responsible for that problem as the folks that know how to write in C;
> perhaps even more so.
>
> I implore you to add your skills to improving the documentation. You have
> the ability to see the documentation from a completely different
> perspective from the folks that wrote the code. They may not have
> documented --remote-host because they perhaps added it for an internal
> reason and didn't expect users to use it. By looking at it from a different
> perspective, you may see a need for documentation and have the ability to
> implement it.
>

I globally agree with your statement but there's a catch here, more of a
chicken-and-egg problem actually! In order to contribute to the
documentation or help other users, I must first be able to understand the
project myself! The mere documentation is missing at almost every stage in
GlusterFS and this is problematic. If I'm not able to put GlusterFS at use
understanding how it works and how it interacts between all of its
components, how am I supposed to explain it to other people?

I'm a sysadmin for over 2 decades and this is the first time I see such a
major project (GlusterFS is not a small HelloWorld app, it's featureful,
complex and envolves learning some concepts) with so little documentation.
As I said before, I currently have *no* *clue* of all the options and
directives I can use in the main configuration file
/etc/glusterfs/glusterd.vol for example! There's only a "sample"
configuration file with no further detail than the classic "paste this into
the file". Well no thank you ;) I won't paste anything to any configuration
file without understanding it first and have a complete set of directives I
can use. I have the reponsability of having a running service and can't
just "paste things" as told :-)

The only way I got GlusterFS to work is by searching BLOG posts and this
bad IMHO. The way I see how a project ecosystem should be managed is like
this : The devs should not only code but provide the full information,
documenting every single option and directive because no other than them
know the project better than they do! After that, the ecosystem will grow
by itself thanks to technical people that create blog posts and articles to
explain various creative ways of using the software. The documentation from
the devs does not have to be ultra exhaustive explaining all possible use
cases of course but at least, document everything that needs to be
documented to let other people understand what they are dealing with.

Let me take 2 real world examples to get the general idea : Postfix and
NGinX! They are flexible enough to provide a quite large set of use cases.
Their documentation is impeccable from my point of view. They provide an
exhaustive documentation of their inner options like this -
http://www.postfix.org/postconf.5.html - and this -
http://nginx.org/en/docs/dirindex.html

See, even if you forget all the HowTo's, articles and stuff, which are
great additions and bonuses, you can manage to get out of the woods with
these docs. That's exactly what I miss most in GlusterFS. There are here
and there options explained but often with no context.

To the very specific case of "--remote-host" option, there's a design
problem in "gluster" command. Launching it without arguments and you get a
prompt and the command completion helps a bit. Now, try "gluster -h" (or
--help or -? or whatever) and you end up with "unrecognized option --XXX".
This is counter intuitive again. You can't experiment by trial and error to
figure out things when you're in the dark, that's why I had to take a peek
to the source code and find out the existence of other options.

If you spend so much time trying to find information instead of
experimenting with a project, you may grow bored and leave. This would be
bad because the lack of documentation may lead people to avoid a project
which could be really useful and good! GlusterFS features exactly what I
want for my usage, that's why I picked it up but I didn't think it would be
so hard to get proper documentation.

For example, I can't get SSL to work with my 3.6.2 setup and there's not a
single bit of doc about it. There's only
http://blog.gluster.org/author/zbyszek/ but even after following the
necessary steps, I end up with a cryptic log entry "Cannot authenticate
client from fs-00-22666-2015/03/16-11:42:54:167984-Data-client-0-0-0 3.6.2"
and repeated for all the replicas :-( I don't know what GlusterFS expects
in this case so I can't solve the problem for now.

I'll stop boring you now, you get the point ;) You can only explain what
you clearly understand and for now, this is still way too foogy for me :)

-- 
Unix _IS_ user friendly, it's just selective about who its friends are.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-users/attachments/20150317/b357a41e/attachment.html>