[Gluster-users] Why revamp Gluster.org?

[Soumya Deb]

To avoid getting lost in long paraphrasing - very much agreed with Joe.

MediaWiki or else, docs needs a platform essentially "meant for docs".
And shouldn't be a sub-part of the promo-page/landing site's contents.

The way /documentation does it for now, is barely scalable, if ever.

<ignore>
The analogy can closely relate to making CPUs do graphics intensive job
while we've made enough technical progress to use GPUs to do it better.
</ignore>

[Again] in my original proposal - I've never meant to include docs as
the main landing site content - if that message wasn't clearly conveyed.


> 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.