<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">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.<br>
<br>
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.<br>
<br>
When I create the html version, I plan on stripping off the ##_ so
the page names will be like admin_console.html<br>
<br>
Thanks for getting involved in this. It's been something that I've
wanted to do for a while.<br>
<br>
On 07/30/2013 12:06 PM, Kaushal M wrote:<br>
</div>
<blockquote
cite="mid:CAOujamUe=zeuqjiNzki9tHbt5Whw8p-hWYRWLm6gX6d9TMe+pw@mail.gmail.com"
type="cite">
<p dir="ltr"><br>
On 30-Jul-2013 8:23 PM, "Vijay Bellur" <<a
moz-do-not-send="true" href="mailto:vbellur@redhat.com">vbellur@redhat.com</a>>
wrote:<br>
><br>
> On 07/30/2013 06:56 PM, Lubomir Rintel wrote:<br>
>><br>
>> Hello everyone,<br>
>><br>
>> I've found GlusterFS documentation hard to follow. I've
often found<br>
>> resources useful to me only by accident, scattered
across the wiki, in<br>
>> source tree, blogs or presentation slides. Lots of
documents were on<br>
>> the other hand inaccurate or incomplete, maybe just
because GlusterFS<br>
>> development progressed making them obsolete. The more I
got involved<br>
>> with GlusterFS use, the more I wished for a consistent
guide/book I<br>
>> could follow to grasp understanding of ideas behind its
architecture<br>
>> as well as implementation.<br>
><br>
><br>
> +1. A lot of information is scattered and there is no good
mechanism to integrate the useful stuff and leave out the noise.<br>
><br>
><br>
>><br>
>> I would very much like to help improve the situation
(as time would permit).<br>
>><br>
>> I'm not sure how, though, and need some help with that.
What I'd like<br>
>> to avoid is clashing with anyone's else work, or
preparing patches<br>
>> that would get immediately refused. I've prepared an
short analysis of<br>
>> current documentation and overview of what would
changes make sense to<br>
>> me:<br>
>><br>
>> <a moz-do-not-send="true"
href="https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas">https://github.com/lkundrak/glusterfs/wiki/Documentation-improvement-ideas</a><br>
>><br>
>> I'd be very thankful for feedback, especially from
people that are<br>
>> working on documentation currently, have plans about
changes to it or<br>
>> are familiar with history behind current situation.
"This does not<br>
>> make any sense," or "Go ahead, do this!" would
definitely be<br>
>> appreciated.<br>
>><br>
><br>
> I will try to provide a section-wise feedback of your doc
on where we stand today and what can be done.<br>
><br>
> General ideas:<br>
><br>
> 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.<br>
><br>
> 2. A well structured doc/ folder to be the container for
all documentation.<br>
><br>
> 3. Adding a developer/hacking section in addition to
admin-guide would be nice to have.<br>
><br>
> Admin Guide:<br>
><br>
> 1. All in markdown. Need to evolve a process to roll down
the latest admin guide on to <a moz-do-not-send="true"
href="http://gluster.org">gluster.org</a>.<br>
><br>
> 2. 3.1.x and 3.2.x documentation is relevant for the
respective releases.<br>
><br>
> 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.<br>
><br>
> User Guide:<br>
><br>
> 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.<br>
><br>
><br>
> Hacking GlusterFS:<br>
><br>
> 1. Most individual files not up to date. Concur that it
would be good to make it current and convert this to markdown.<br>
><br>
> 2. Even the development work flow can be converted to a
markdown document.<br>
><br>
> 3. The Arch and Presentation sections can be made more
accessible in the website.<br>
><br>
> Translator reference:<br>
><br>
> 1. legacy references can be removed.<br>
><br>
> 2. <a moz-do-not-send="true"
href="http://gluster.org/community/documentation/index.php/Gluster_Translators">http://gluster.org/community/documentation/index.php/Gluster_Translators</a>
- looks mostly random, a better table can be generated from the
o/p of "volume set help" and/or from code.<br>
><br>
> 3. <a moz-do-not-send="true"
href="http://gluster.org/community/documentation/index.php/Translators">http://gluster.org/community/documentation/index.php/Translators</a>
- incomplete, but might be a good starting point.<br>
><br>
> 4. More information on translators can be part of the
developer<br>
><br>
> volfiles:<br>
><br>
> can be git rm -rf'ed<br>
><br>
> Random:<br>
><br>
> 1. All legacy stuff can be git rm -rf 'ed<br>
><br>
> 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.<br>
><br>
> 3. doc/glusterd.vol is packaged. Can probably move to
extras.<br>
><br>
> Manual Pages:<br>
><br>
> To be cleaned up and brought up to date.<br>
><br>
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).<br>
Since, pandoc supports generation of man pages from markdown, if
do this conversion it'll be easier to maintain them.</p>
<p dir="ltr">~kaushal <br>
><br>
> 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 ;-).<br>
</p>
</blockquote>
<br>
</body>
</html>