[Gluster-users] Why revamp Gluster.org?

[Soumya Deb]

Thanks for your inputs, Tuomas!

> > This could be as simple as: `git pull`
> > Instead of generating, having a ground up static site can solve this for
> > us.
> 
> This is actually not true. The middleman / ruby framework is wired up
> so that it builds the site when you push the change. For a simple typo
> it's no different to what there is now. You can correct a typo and push a
> fix.

As in, directly to the prod-server?


> It is however a good idea to generally check that your changes build
> correctly and don't break things, just like how you do with code.

Yup, and as less number of steps/deps there, the better - right?


> > 2. For developers:
> > 
> > [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.
> 
> This all depends on your own perspective and what you already know. To
> contribute content, you don't need to understand any of the framework. You
> edit a chapter of Markdown in an existing page, or create a new one in a
> folder. Markdown is designed to be easy to read and write. This email is
> very similar to the markdown syntax.
> 
> You don't really need to touch the templates or styling or that stuff if
> you want to add *content*. Everything else is for the people who actually
> *design* the website look and feel. And to do those, you need to define them
> somewhere anyway.

The most of the content, as we can imagine, should and would live on the docs.
With that, the landing page is would be more of markup/layout than paragraphs.
I do agree, markdown and other such subset-markups make it easy for content
creation, they're no why an HTML/CSS competitor when it comes to layout.

Say, http://code.debs.io/glusterweb which part can be written better in MD?
It's nearly pointless to write just the header, footer, or buttons in MD.


> HTML, CSS and Javascript are not really any "easier" to learn for a newcomer,
> you are just already familiar with them.

Yes, I agree that "easy" is a subjective term, with bias on familiarity.

An on the same note, stat says, more people are familiar with HTML/CSS/JS
than people who are familiar with static site gens, deps resolution, and/or
particular markup lang. HAML isn't any easier to master without knowing HTML.


> We are not really lacking in people who do web development, we want people
> to contribute *content*.

On the docs site, yes.
The landing page just needs the pitch & pointers to the docs for content.

Content creation & maintenance on the main website will create fragmentation
of information & redundant efforts of fixing it - as it already has:

http://www.gluster.org/documentation/
http://www.gluster.org/community/documentation/

And the reason it is like that now, is because we started walking in that way
once. This is the reason why we should be looking for system/setups which (may)
need more planning but less maintenance. It's the opposite way right now.


> How about we combine our ideas?
> 
>   * We could move the site git repo to github to make it easier to contribute
>     (since many people have accounts already)

GitHub over Gitorious, yes (for various practical reasons).
I think we should have a sync git-mirror though - just in case GH goes rogue.


>   * We could then use the github "edit this file" feature to make changes
>     to the content files, and people could use Markdown/asciidoc syntax,
>     because it is much easier to work with than writing HTML.
>     <p class="point"><b>Because brackets and markup are <i>great</i> for
>     computers</i> &mdash; but writing them by hand (and <a href="#">spotting
>     missing brackets and other mistakes!) is pretty annoying for regular
>     human beings.</b></p>

This is a fallacy of cherry picking sort. The part you missed is, with the
current repo, there's no way to verify my change actually worked, or not,
or broke something else - until it's pushed to server.

OR, is tried & tested locally by the editor, OR, to get a VM and set up the
automated rigging of taking repo HEAD & building on each push & stage them.

In which case, the ease of being able to edit files on GH doesn't earn value.
If I'm being unable to explain this part, please do let me know.


> > 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.
> 
> You do not need to learn to use the framework to write content.

That concern also doesn't fit here - as content creators will have upcoming
docs.gluster.org to contribute in to. They don't need to edit landing page.

May it be markdown, wiki, ascii - not at all tightly-coupled with main site.


> An alternative way to contribute:
> 
>   * Start a temp git repository in github and write a markdown page
>   (index.md)
> 
>   * Edit it with the github web editor, save (makes a git push) and view it
>     directly in github. Github does render it for you so you can see
>     everything
>     works correctly.
> 
>   * Submit the file as a merge request or just mail the list and ask it to
>     be included if yo ufeel intimidated by the framework.

You mean, decommissioning the current repo?


> > 2. For visitors:
> > A website built with many moving pieces, fragile gears & wheels will tend
> > to break, point to wrong/confusing locations, introduce fragmentation &
> 
> A single html page is always easy. If you want to add more content, you will
> need to have some kind of templating system to maintain consistent navigation
> and such anyway..?

Probably I haven't been able to phrase it well, but added contents, guides can
and should go into docs. This point also doesn't help in your argument.

When it comes to discovery, contents spread across multiple pages are less
preferred than scroll down interface (not talking about pagination vs infinite
scroll). For the amount of content we'll have for our site - a single page can
totally suffice - and doesn't even need the templating system (and build step).

Skipping research papers; this is simple version of what I'm trying to explain
http://uxmovement.com/navigation/why-scrolling-is-the-new-click/ - pros & cons
are there, for us less clicks brings more value (as we're not into analytics)

Just to add to this, and avoid an accidental straw man being pulled - I'm not
proposing an incredibly long page. The page length won't be much longer than
what we currently have (each compared on mobile or desktop).

Hope I've been able to explain better this time why:
1. we don't need templating, and hence the build/middleman, in turn
2. putting up current repo on github doesn't have same effect as the new one
3. we don't *need* the bulk of content on the landing page (& markdown)
4. we can totally make a single landing page with proper pointers work better
5. more *contents* we have on landing page, less organized documentation gets
6. simpler the architecture (when affordable), less painful it is to maintain

If anything I've explained doesn't make sense, please do correct me.

Either path may we choose to go, let's all have a very clear reasoning and
understanding *why* or *why not*?