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