On 03/16/2015 10:24 PM, Melkor Lord wrote:> > On Mon, Mar 16, 2015 at 5:14 AM, Joe Julian <joe at julianfamily.org > <mailto: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?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.htmlPostfix, 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 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://www.gluster.org/pipermail/gluster-users/attachments/20150316/eb2aa98f/attachment.html>
Joe Julian [Mon, Mar 16, 2015 at 11:43:12PM -0700]:> Good question. It took me months to figure all that out (with far less > documentation than there is now) [...]... just wondering: Why don't we run a kickstarter/indiegogo campaign to finance people to write (from scratch?) documentation? There are various good examples of GREAT documentation for various projects and given that glusterfs is an evolving software that becomes more popular, it could be a way to improve documentation and thus experience with glusterfs. -- New PGP key: 659B 0D91 E86E 7E24 FD15 69D0 C729 21A1 293F 2D24
On 03/17/2015 01:43 AM, Joe Julian wrote:> 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 good as that guide is, I see that as an issue. The documentation page has an "Administrator Guide" link that goes to... the markdown source on github (same link you posted). Couldn't a PDF be built from that in CI and linked to from the documentation page? It would be a lot easier to use (and give a better impression than "here, look at the source"). -- Glenn Holmer (Linux registered user #16682) "After the vintage season came the aftermath -- and Cenbe."
On Tue, Mar 17, 2015 at 7:43 AM, Joe Julian <joe at julianfamily.org> wrote: 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> > . >I really think that this github doc (administrator's guide) should be used directly on gluster.org replacing most, but not all, of the existing doc because it's clearly more useful (IMHO) than the doc available on site. It just needs some additions like this - http://www.gluster.org/community/documentation/index.php/Gluster_3.2:_Setting_Volume_Options - which sysadmins love ! A comprehensive list of options/directives, their meaning and their default values. There is useful documentation on gluster.org, mainly the howto's but for example, I don't think this kind or stuff - http://www.gluster.org/documentation/architecture/internals/Dougw:A_Newbie%27s_Guide_to_Gluster_Internals/#Configuration_and_Vol_Files - can help anyone. A bunch of "sample" configs and no pointers to how to fill them with useful values. Hint: When you have to use a search engine and type "site:gluster.org nfs" to reach the link in the first paragraph, something is clearly wrong on how the documentation is built on site.> 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. >If you read my first post - http://www.gluster.org/pipermail/gluster-users/2015-March/021070.html - especially the point "1/", you'll *why* I had to mess with it. BTW, I also pointed the inconvenience of using "transport.socket.bind-address" which is needed in my case but unusable in the current state. And sorry but "You don't need to mess with that" is not a good answer, this something for Apple users who "don't want and don't need to know what's under the hood" :-) For example, I have no use for "rdma" in my case and want to disable it to avoid adding bloat to my logs (already huge by default) complaining about not being able to initialize it.> That is the way it's done, btw. The developers are required to document > their features before a release. >Ok so where's the doc for the features for "glusterd.vol" ? :-)> 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 used postfix when its version was 1999MMDD :-) It took these examples to demonstrate that they are comprehensive despite their visual awfulness. Docs like Apache or PHP or Python are way more appealing for the eye of the reader. The point was : First provide exhaustive documentation, then add eye candy. For instance, the markdown docs available on GitHub are a very good balance between these goals.> > 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. >I'm not putting a trial on gluster, don't take me wrong. The biggest issue I have is with the way documentation is available. Now that I browsed a lot of it I get a clearer view of the big picture. Currently, it is available at 3 distinct places, here - http://www.gluster.org/documentation/ - here - http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide and finally here - https://github.com/gluster/glusterfs/tree/master/doc/admin-guide/en-US/markdown which does not really help anyone discovering the project. Mixing various information available on each site allowed me to get GlusterFS work reasonably well for my needs except for the SSL part (but given the SSL markdown doc, I think I know how to solve my issue, I still have to test)> 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. >You missed the point here. Yep, "gluster help" works nicely and is quite helpful but I was talking about the options for "gluster" itself, independently of any command! You *HAVE* to look here - https://github.com/gluster/glusterfs/blob/master/cli/src/cli.c#L303 - to find out that "gluster" accepts "--version", "--print-logdir", "--remote-host=", etc, etc. This is not documented elsewhere AFAIK.> 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. >I think a third (maybe the right one this time) is need to gather all scattered documentation, remove the not-so-useful stuff and add documentation for what's missing.> 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 >That's the result of scattered information. I spent so much time searching for glusterd.vol information, and had to deal with the "transport.socket.bind-address" issue that I simply missed that one. I confess having spent most of my time within here - http://www.gluster.org/community/documentation/index.php/Gluster_3.2_Filesystem_Administration_Guide - and here - http://www.gluster.org/documentation/ Trust me to thoroughly read this SSL markdown doc to try to solve my issue :-)> 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. >I wish you the best of luck on that because I know what writing doc means, it's an unfair job. I sometimes have to write doc, mainly tutorials with screen captures, for users who never read it and complain the usual "it doesn't work" BS. At least you'll be luckier with GlusterFS because your target audience is technically skilled people who know they have to actually read docs to make things work :-)> 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 >As mentioned earlier, I indeed had to browse the source code to find the options of the "gluster" command. I agree there are obvious options and it's no rocket science to guess what their arguments are but for others, I wouldn't roll the dice to "guess" what it does. Documentation is far too important to be messed with :-D -- 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/20150318/f93c256c/attachment.html>
On Tue, Mar 17, 2015 at 7:43 AM, Joe Julian <joe at julianfamily.org> wrote:> > > > https://github.com/GlusterFS/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ssl.md >Small note to tell that I got SSL working properly as I wanted, thanks :-) -- 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/20150319/352e50d6/attachment.html>