[Gluster-users] Why revamp Gluster.org?

[Aravinda]

On 04/10/2015 03:54 PM, Soumya Deb wrote:
> 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.
I agree, we should have static html for home page, all the other pages 
should have template and supporting Markdown page.
For doc pages, we should use Markdown for adding content and Theme 
should be in place in repo.

HTML/JS/CSS work should be only during initial stage and whenever home 
page revamp required. All the other contributions should be via 
Markdown. Even in homepage, all the links like Twitter, Download link 
etc should be populated using config file, So that changing these 
details will be easy.

How about using Pelican(http://blog.getpelican.com/) for generating 
static site? Pelican is a Python based popular static site generator.(My 
website http://aravindavk.in is created using Pelican, with my own 
custom theme)

Workflow will be,
Install using `sudo pip install pelican` and clone Gluster website 
repo(git clone)
Modify required files,
make html
make serve => View preview by opening http://localhost:5000 in any browser.
If all changes looks good then Submit the changes to gerrit.
Automatic post commit hook on server generates website once changes gets 
merged.

I can help to create Themes or convert finalized html design into 
Pelican theme etc. Let me know any help required.

>
>
>> 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.
Separate repository for website/documentation should be created. Reason, 
If anyone wants to contribute for website/doc need not clone entire 
GlusterFS source code.
Pelican(http://blog.getpelican.com/) is simple and more customizable 
than Github's Jekyll or any other static site generators.
>
>
>>    * 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*?
> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-users

~aravinda