The docs (markdown version) are in
doc/admin-guide/en-US/markdown for release-3.4 and master. I'd
like to have these converted for 3.3 as well.
I started to automate the publication of the existing content but
I noticed some deficiencies in order to make it happen. I need a
title page that links to the chapters and the chapter files need
to be renamed such that they can be ordered correctly when
assembling a pdf or edoc, such as 01_admin_console.md,
02_admin_storage_pools.md, etc.
When I create the html version, I plan on stripping off the ##_ so
the page names will be like admin_console.html
Thanks for getting involved in this. It's been something that I've
wanted to do for a while.
On 07/30/2013 12:06 PM, Kaushal M wrote:
On 30-Jul-2013 8:23 PM, "Vijay Bellur" <vbellur@xxxxxxxxxx>
wrote:
>
> On 07/30/2013 06:56 PM, Lubomir Rintel wrote:
>>
>> Hello everyone,
>>
>> I've found GlusterFS documentation hard to follow. I've
often found
>> resources useful to me only by accident, scattered
across the wiki, in
>> source tree, blogs or presentation slides. Lots of
documents were on
>> the other hand inaccurate or incomplete, maybe just
because GlusterFS
>> development progressed making them obsolete. The more I
got involved
>> with GlusterFS use, the more I wished for a consistent
guide/book I
>> could follow to grasp understanding of ideas behind its
architecture
>> as well as implementation.
>
>
> +1. A lot of information is scattered and there is no good
mechanism to integrate the useful stuff and leave out the noise.
>
>
>>
>> I would very much like to help improve the situation
(as time would permit).
>>
>> I'm not sure how, though, and need some help with that.
What I'd like
>> to avoid is clashing with anyone's else work, or
preparing patches
>> that would get immediately refused. I've prepared an
short analysis of
>> current documentation and overview of what would
changes make sense to
>> me:
>>
>> https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas
>>
>> I'd be very thankful for feedback, especially from
people that are
>> working on documentation currently, have plans about
changes to it or
>> are familiar with history behind current situation.
"This does not
>> make any sense," or "Go ahead, do this!" would
definitely be
>> appreciated.
>>
>
> I will try to provide a section-wise feedback of your doc
on where we stand today and what can be done.
>
> General ideas:
>
> 1. Consistent format for documentation would be markdown.
There are some thoughts on moving to asciidoc but given limited
asciidoc support in pandoc, we can live with markdown for now.
>
> 2. A well structured doc/ folder to be the container for
all documentation.
>
> 3. Adding a developer/hacking section in addition to
admin-guide would be nice to have.
>
> Admin Guide:
>
> 1. All in markdown. Need to evolve a process to roll down
the latest admin guide on to gluster.org.
>
> 2. 3.1.x and 3.2.x documentation is relevant for the
respective releases.
>
> 3. Basic_Gluster_Troubleshooting, GlusterFS_Concepts,
QuickStart, Getting_started_overview are not yet in the git
repo. Might be good to have them in markdown too.
>
> User Guide:
>
> Mostly legacy stuff, have not been touched in years. We can
probably clean them up from the repo if they cannot be easily
massaged to reflect the current state.
>
>
> Hacking GlusterFS:
>
> 1. Most individual files not up to date. Concur that it
would be good to make it current and convert this to markdown.
>
> 2. Even the development work flow can be converted to a
markdown document.
>
> 3. The Arch and Presentation sections can be made more
accessible in the website.
>
> Translator reference:
>
> 1. legacy references can be removed.
>
> 2. http://gluster.org/community/documentation/index.php/Gluster_Translators
- looks mostly random, a better table can be generated from the
o/p of "volume set help" and/or from code.
>
> 3. http://gluster.org/community/documentation/index.php/Translators
- incomplete, but might be a good starting point.
>
> 4. More information on translators can be part of the
developer
>
> volfiles:
>
> can be git rm -rf'ed
>
> Random:
>
> 1. All legacy stuff can be git rm -rf 'ed
>
> 2. features is a placeholder directory that we created to
host documentation on features. Can be moved to more appropriate
locations as part of the cleanup. All sources have to be in
markdown.
>
> 3. doc/glusterd.vol is packaged. Can probably move to
extras.
>
> Manual Pages:
>
> To be cleaned up and brought up to date.
>
Can we also try to move the man pages to markdown as well? I
tried to update them for the 3.3 release, but wasn't able to get
much done because the markup language used is hard to make sense
of (at least for me).
Since, pandoc supports generation of man pages from markdown, if
do this conversion it'll be easier to maintain them.
~kaushal
>
> Thanks for your effort in putting this together. I am all
for getting documentation to a better place than where it is
today and given where we are, it might not be a very hard
exercise initially ;-).
