|
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@xxxxxxxxxxx
http://www.gluster.org/mailman/listinfo/gluster-users
_______________________________________________
Gluster-users mailing list
Gluster-users@xxxxxxxxxxx
http://www.gluster.org/mailman/listinfo/gluster-users
_______________________________________________
Gluster-users mailing list
Gluster-users@xxxxxxxxxxx
http://www.gluster.org/mailman/listinfo/gluster-users
|
