<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
On 03/16/2015 10:24 PM, Melkor Lord wrote:<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra"><br>
<div class="gmail_quote">On Mon, Mar 16, 2015 at 5:14 AM, Joe
Julian <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:joe@julianfamily.org" target="_blank">joe@julianfamily.org</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px
0.8ex;border-left:1px solid
rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"><span class=""> <br>
</span> 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 <b>project</b>. 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.
<br>
<br>
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.<br>
</div>
</blockquote>
<div> <br>
</div>
<div>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?<br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
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.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div><br>
</div>
<div>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. </div>
</div>
</div>
</div>
</blockquote>
<br>
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 <a
href="https://github.com/GlusterFS/glusterfs/tree/master/doc/admin-guide/en-US/markdown">github</a>.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>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! </div>
</div>
</div>
</div>
</blockquote>
<br>
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.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>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 :-)<br>
<br>
</div>
<div>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.<br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
That is the way it's done, btw. The developers are required to
document their features before a release.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>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 - <a moz-do-not-send="true"
href="http://www.postfix.org/postconf.5.html">http://www.postfix.org/postconf.5.html</a>
- and this - <a moz-do-not-send="true"
href="http://nginx.org/en/docs/dirindex.html">http://nginx.org/en/docs/dirindex.html</a><br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
Postfix, 16 years old, and hasn't always had very detailed
documentation. Do you also remember when it was worse than
sendmail's?<br>
<br>
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.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div><br>
</div>
<div>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.<br>
<br>
</div>
<div>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.<br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
"gluster help" is pretty intuitive, imho, as is<br>
<br>
# gluster<br>
gluster> help<br>
<br>
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.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div>If you spend so much time trying to find information
instead of experimenting with a project, you may grow
bored and leave.</div>
</div>
</div>
</div>
</blockquote>
<br>
Agreed, and that's something that the gluster.org web site's been
failing at since the last 1 or 2 web site revamps.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<div> 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.<br>
<br>
</div>
<div>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 <a moz-do-not-send="true"
href="http://blog.gluster.org/author/zbyszek/">http://blog.gluster.org/author/zbyszek/</a>
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.<br>
</div>
</div>
</div>
</div>
</blockquote>
<br>
<a class="moz-txt-link-freetext" href="https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md">https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md</a>
<-- not a blog<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra"><br>
</div>
<div class="gmail_extra">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 :)<br clear="all">
</div>
<div class="gmail_extra"><br>
</div>
</div>
</blockquote>
<br>
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.<br>
<br>
<blockquote
cite="mid:CAOXaFyy==KXAPnLNzNf5yLoaJa4A9tsd9YZ1OZCgaEZGd0YSCA@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">-- <br>
<div class="gmail_signature">Unix _IS_ user friendly, it's
just selective about who its friends are.</div>
</div>
</div>
</blockquote>
<br>
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. <span
class="moz-smiley-s5"><span> :-D </span></span><br>
</body>
</html>