[Gluster-infra] Documentation page concerns.
lmohanty at redhat.com
Thu Jan 8 08:48:34 UTC 2015
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.
> 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.
>> 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:
> (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.
More information about the Gluster-infra