[Gluster-users] Why revamp Gluster.org?

Tue Apr 14 09:37:26 UTC 2015

On 04/14/2015 04:43 AM, Joe Julian wrote:
> 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.
>

Agree to most of your points. Wiki pages have its own value.

However it puts us in a difficult place with respect to addressing 
following issues

  *  From technical accuracy point of view, we need version control as
    instructions might differ from release to release.
  * Also we have seen users complaining the documentation is scattered
    as of now and making it hard to contribute to documentation. So we
    need to fix that too.
  * Wiki pages do not have ownership around it, which in turn result in
    ill-maintained pages.

Let us know your thoughts about the above issues.

Thanks,
Lala
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
>
> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-users/attachments/20150414/c66ef9c7/attachment.html>