[Gluster-devel] Inspiration for improving our contributor documentation

[Justin Clift]

On 18/07/2014, at 6:52 AM, Kaushal M wrote:
<snip>
> These kinds of docs need to indexable and searchable by search
> engines. Only then will they be useful. I don't think markdown files
> in the source would be good place for these.
> The other docs related to source/code documentation can be provided in
> the source as we are attempting to provide now. These need to be
> directly accessible for devs when developing, so having them in the
> git repo is good.

 
Background info: The new-look website is generated from static files
(using "Middleman").  The repo is on the forge (I don't have the URL
atm).

Anyway, maybe we can add a step/plugin/script/whatever that grabs the
.md files from the glusterfs source, and renders them into pages on
the new-look website.  (updating every time the website is generated)

As long as the resulting URLs are stable (eg same .md file results in
same URL), that'd be stable for search engines.

We _might_ be able to include .svg this way too, which may turn out
to be useful.  .svg is pretty compact, and pictures can really help
sometimes when explaining concepts.

Worth considering?

+ Justin

--
GlusterFS - http://www.gluster.org

An open source, distributed file system scaling to several
petabytes, and handling thousands of clients.

My personal twitter: twitter.com/realjustinclift