[Gluster-infra] Documentation page concerns.

[Lalatendu Mohanty]

On 01/07/2015 07:26 PM, Tuomas Kuosmanen wrote:
> 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.

That would be great to hear from past experience and use it for Gluster. 
The current guidelines are at below location.

http://www.gluster.org/community/documentation/index.php/Main_Page#Documentation_for_GlusterFS 

>
> 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 :-)
Yes, we have discussed and agreed to create something like 
wiki.gluster.org or docs.gluster.org in the past. I think Humble was 
trying to create it, but not sure what is the current status.
> (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.

It is actually the original Admin guide for GlusterFS which is converted 
in to markdown format.
>
> 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.
I am fine with anything, as long as users get the relevant information.

-Lala