[Gluster-infra] Documentation page concerns.

[Tuomas Kuosmanen]

I cc:ed Shaun (hi! :-) are you on the list?) - He has experience 
from the GNOME documentation project in the past. We should 
discuss how to do the Gluster documentation effort in general - 
who writes them, what tools do we want to use and what is the workflow
to get the docs written and published on the site.

For example there is the wiki, we coukd make it more generic (like,
gluster.org/wiki or wiki.gluster.org and have one section be a community
area where, among other things, documentation project can plan and draft 
documentation? Whether the whole documentation can live in a wiki is
another good question - but I wish to have Shaun's comments on this as well,
since I don't have much background in documentation. I want to avoid
hitting my head in the walls others have already had their shot at :-)

(rest of the reply inline below)

----- Original Message -----
> From: "Soumya Deb" <deb at redhat.com>
> Subject: Re: [Gluster-infra] Documentation page concerns.
> 
> With Humble's help, I discovered that the updated docss live in markdown
> format in the source itself.
> 
> For e.g.
> https://github.com/gluster/glusterfs/tree/master/doc/admin-guide/en-US/markdown
> 
> It may be worth looking into, using RawGit.com (as the source lives on GH)
> displaying the same in-source docs on the website.

Looks like the admin-guide is a separate document (or a number of 
related chapters focusing on various topics) and developed in github, 
separate from the rest of the docs.

The rest of the docs are on site and I think we really should revisit the
whole documentation vision and toolset before doing any extensive hacks. Are 
the current docs up to date? Do they make sense? Etc..

Speaking of that admin guide, github renders the markdown pretty ok 
it seems, wouldnt it be a temporary solution to link to these from the
documentation index like this:

https://github.com/gluster/glusterfs/blob/master/doc/admin-guide/en-US/markdown/admin_ACLs.md
(an example)

It is a bit silly since it jumps to github and loses our
navigation and site context, but at least it shows the document, 
and the reader can get the information he/she needs.

//Tuomas