[Gluster-users] Why revamp Gluster.org?

Mon Apr 13 23:13:26 UTC 2015

Wiki process:
1. user reports instructions are failing
2. click the link for the failing instructions
3. identify the problem with the instructions
4. click edit
5. edit
6. save
Average total time: 2 minutes

Static process:
1. user reports instructions are failing
2. click the link for the failing instructions
3. scan through the page for some unique text that you can use to find 
this page
4. git pull
5. git grep <text for step 3>
6. go back to step 3 and look for something else because the text wasn't 
found
12. edit the text
13. git commit -a -m 'repairing instructions that could never have 
worked in the first place'
14. see if the changes show up the next day

In the mean time, that user has now made a blog post about how unusable 
gluster is. "They can't even write simple instructions for how to 
install it."
Average total time, 15 minutes

And that's only if you have permissions and know what you're doing. If 
the average user sees that typo that needs fixed, it's not going to 
happen when they can't just click "edit". They're not even going to tell 
you about it. We're professionals with jobs to do. Our jobs are are 
completely unlike development. We're not just responsible for getting 
our code into the project and ensuring it passes. We're responsible to 
customers with SLAs. We have time based commitments that have to be 
adhered to. If we have to take the time to learn how to contribute, it's 
just not going to happen.

On 04/13/2015 03:48 PM, Joe Julian wrote:
> Just keep this in mind when revamping:
>
> [15:17] <mike2512> hey guys... i am trying to install gluster on 2 
> centos vms  - centos 6.6
> [15:17] <mike2512> Requires: libgfapi.so.0(GFAPI_3.4.0)(64bit)
> [15:17] <mike2512> i have followed the procedures here: 
> http://www.gluster.org/community/documentation/index.php/Getting_started_install
> [15:19] <JoeJulian> Er... That probably could have been done a lot 
> better. Let me edit that page.
> [15:21] <mike2512> JoeJulian: yeah... the page is not updated.. the 
> commands for centos are for an older version... but still.. with the 
> rpms that i get... i can't install. .... this is a bad thing.. 
> especially that now i want to see how good the product is... and from 
> the start i get an error :P
> [15:22] <mike2512> is centos 6.6 supported? or i should move to 7 ?
> [15:22] <mike2512> i have installed also the development tools
> [15:23] <JoeJulian> There you go mike2512
> [15:23] <JoeJulian> I've fixed it.
> [15:24] <mike2512> already?!
> [15:24] <mike2512> wow
> [15:24] <JoeJulian> It wasn't hard. Just had to mostly delete a bunch 
> of crap.
> [15:25] <mike2512> JoeJulian: you are an effing STAR
> [15:27] <mike2512> thanks JoeJulian
> [15:31] <JoeJulian> You're welcome
> [15:42] <JoeJulian> ... and then I see that the static docs on 
> gluster.org have the same garbage. ... why do we have to have the same 
> content duplicated in a static page that nobody will ever edit? 
> There's a reason wikis exist.
> [15:44] <mike2512> well... what is the current documentation?
> [15:44] <JoeJulian> Since I just changed it, the wiki.
> [15:44] <JoeJulian> Now, I guess, I'm expected to change it again 
> through a git commit.
> [15:45] <JoeJulian> ... not going to happen. I've got things to do.
>
>
> On 04/08/2015 08:27 AM, Soumya Deb wrote:
>> Hello all,
>>
>> I came to realize, the entire discussion about why to revamp Gluster 
>> website is fragmented across threads & links. Thought it might be a 
>> good opportunity to post a brief, yet cover-all write up on why this 
>> is necessary.
>>
>> There are three primary facets to the challenges we are facing, and 
>> I'm also listing their prospective solutions:
>>
>> 1. For devops:
>>
>> Presently, the devop/deployer needs to handle
>>   - a readme: 
>> https://forge.gluster.org/gluster-site/gluster-site/blobs/master/README.md
>>   - a config: 
>> https://forge.gluster.org/gluster-site/gluster-site/blobs/master/config.rb
>>   - & script: 
>> https://forge.gluster.org/gluster-site/gluster-site/blobs/master/setup.sh
>>
>> ^ that's even if it's just a typo fix.
>>
>> This could be as simple as: `git pull`
>> Instead of generating, having a ground up static site can solve this 
>> for us.
>>
>>
>> 2. For developers:
>>
>> [Part 1: DevEnv Setup]
>> Presently, one needs to download and install quite some dependencies 
>> (most of which a web-dev may not even need for any other purpose 
>> ever) to get started; the overhead is even higher if using no/nix 
>> platform.
>>
>> This could be as easy as, drag & drop the index.html on your browser 
>> - being completely static site, it should work fine (Look ma, just 
>> file:// protocol!). Essentially, a browser & a text editor is all one 
>> would need to start with.
>>
>> [Part 2: Learning Curve]
>> Presently, one needs to understand not only HTML, CSS, JS but also 
>> HAML, templating/partials, SASS, YML and so on, going through 
>> hundreds of files, trying to understand how stuff works, with a 
>> combination of technologies so incredibly niche, barely anyone would 
>> feel like home rightaway after cloning it.
>>
>> The learning curve could be as low hanging as the basic web 
>> technology, and just that. No abstraction layers, templates, 
>> compilers, preprocessors - unless there's a very good reason/need for 
>> it (probably not). Essentially, having a much wider prospective 
>> contributor base on its codes.
>>
>> [Part 3: Stage/Showcase]
>> Presently, one needs to run a script each time (s)he makes even a 
>> typo-fixes to get that reflected on their localhost server. To show 
>> around, one needs to get a hosting platform & take explicit steps to 
>> host it (skipping the expense part of it).
>>
>> The staging/showcasing can be as easy as a git push to own fork, and 
>> to be able to check the live web page served at 
>> http://username.github.io/reponame with new code (try 
>> http://debloper.github.io/glusterweb/). Essentially each contributor 
>> having their own staging, including the 
>> http://gluster.github.io/glusterweb/ as the main staging. Easy for 
>> the reviewers and deployers to verify that everything is alright 
>> instead of trial and error.
>>
>>
>> 2. For visitors:
>> A website built with many moving pieces, fragile gears & wheels will 
>> tend to break, point to wrong/confusing locations, introduce 
>> fragmentation & duplication of contents, heftier bandwidth 
>> requirements, responsive regression etc (skipping examples), causing 
>> bad user experience. The number of HTTP requests, the amount of 
>> assets to download, the minimum time required for the site to be 
>> accessible etc. all adds up to this point.
>>
>> If the project is easier to build and manage, it in turn means less 
>> breakage & faster fixes. Also iterative extensions/overhauls won't 
>> also be a nightmare.
>>
>>
>> I'm unsure if I was able to set the tone right; I'm only trying to 
>> make a point why a complete architectural overhaul of the website is 
>> required, and not just a UI or content update. If you have thoughts 
>> or concerns, please do share.
>>
>>
>> Meanwhile, I'm feeling the lack of a Branding guideline for Gluster. 
>> I'd be very much willing to help out Toumas to take this opportunity 
>> & create a brand guideline for Gluster. Also, I'd like to hear from 
>> misc about whether the new proposed model for deployment (git pull ;) 
>> would be more preferred than the current setup (or if there could be 
>> any blocker to go that way).
>>
>> Cheers,
>> Deb
>> _______________________________________________
>> Gluster-users mailing list
>> Gluster-users at gluster.org
>> http://www.gluster.org/mailman/listinfo/gluster-users
>
> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-users