On 03/16/2015 10:24 PM, Melkor Lord wrote:
On Mon, Mar 16, 2015 at 5:14 AM, Joe Julian <j...@julianfamily.org
<mailto:j...@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?
Good question. It took me months to figure all that out (with far less
documentation than there is now) and even with pictures and arrows and
8x10 glossies with a paragraph on the back of each one, people still
have a hard time getting it. That's why so much effort has gone in to
making a cli that does it all for you and doesn't require you to be a
storage engineer to use it.
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.
I'll split this out as I think you're unaware of the admin guide that's
pretty detailed and is, at least, published with the source code (it may
be on the gluster.org site somewhere, but I'm too tired right now to
look). The source can readily be found on github
<https://github.com/GlusterFS/glusterfs/tree/master/doc/admin-guide/en-US/markdown>.
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!
Right. There's nearly no need to mess with that except under the lesser
circumstance that an unprivileged user needs access to the management port.
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.
That is the way it's done, btw. The developers are required to document
their features before a release.
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
Postfix, 16 years old, and hasn't always had very detailed
documentation. Do you also remember when it was worse than sendmail's?
I could counter with any of the myriad of horrible documentation for
some of the most popular software systems out there only to point out
that Gluster's isn't all that bad by comparison to a great many of its
peers.
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.
"gluster help" is pretty intuitive, imho, as is
# gluster
gluster> help
and the more detailed than any other software I can think of, "gluster
volume set help" which has all the settings you can tweak in your volume
along with their description equivalent to that postfix document.
If you spend so much time trying to find information instead of
experimenting with a project, you may grow bored and leave.
Agreed, and that's something that the gluster.org web site's been
failing at since the last 1 or 2 web site revamps.
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.
https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md
<-- not a blog
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 :)
Useful and eloquent perspectives and bits that infra is looking at
rectifying. The web site is covered in too many words. The "Getting
Started" entry has 13 sub-entries. That's not "getting started" that's
"tl;dr". A new vision is being put together that will try to not just
build a fancy web thingy, but will define goals such as usability,
engagement, community interfacing, that kind of stuff - and measure the
effectiveness of the changes that are made. It'll be change for the sake
of improvement rather than just change for the sake of change.
--
Unix _IS_ user friendly, it's just selective about who its friends are.
But I still say you should still document things you find in the source
if they aren't documented - since you're in there anyway. :-D
_______________________________________________
Gluster-users mailing list
Gluster-users@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-users