<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<br>
<div class="moz-cite-prefix">On 08/16/2016 11:42 AM, Humble Devassy
Chirammal wrote:<br>
</div>
<blockquote
cite="mid:CAEAGfOXm2scK683RGCHNfeXdBVDExm4TrVjMT3x=_B3=JZ2F6g@mail.gmail.com"
type="cite">
<div dir="ltr">
<div>
<div>
<div>
<div>Hi Amye,<br>
<br>
</div>
</div>
If I am not mistaken, the RTD search is broken with mkdocs
theme in their hosted ( <project.RTD.{org/io}) platform.
iic, Its also possible that we can host RTD in house and
maintain it. It gives us the freedom of using the same
markdown files with a different theme or customization or
some workaround for the search issue. It looks to me that,
this is what @Gandalf is trying to propose in earlier
threads. <br>
</div>
</div>
</div>
</blockquote>
+1<br>
<br>
From the user perspective, changing the gluster documentation
(again) to a different format is going to be painful.<br>
<br>
People used to bookmark a link, when they visit and resolve a issue.<br>
If user is going to get 404 for these links, I think it's bad.<br>
<br>
We should strive to resolve issues with existing links.<br>
<br>
I can see many readthedocs website where search functionality is
working fine..maybe we should first try what Humble suggested here.<br>
<br>
<blockquote
cite="mid:CAEAGfOXm2scK683RGCHNfeXdBVDExm4TrVjMT3x=_B3=JZ2F6g@mail.gmail.com"
type="cite">
<div dir="ltr">
<div>Its indeed a good move to have more people to contribute
to our upstream documentation. But it has to be <span>weighed</span>
against the existing data. If its going to be continuous help
Red Hat documentation team to improve our documentation,
instead of one shot attempt, we can definitely think about
it. Also, we need acknowledge from the community to shift our
documentation format from Markdown to ASCIIdoc or something
else, which we are trying to figure it out from this thread.<br>
<br>
@Niels, I would like to defend your thought " I have the
feeling only very few people are aware how to send
documentation changes", based on <a moz-do-not-send="true"
href="https://github.com/gluster/glusterdocs/graphs/contributors">https://github.com/gluster/glusterdocs/graphs/contributors</a>
:) .<br>
<br>
</div>
Also, as Prasanth mentioned, when the RTD search issue was
unresolved we gave a try to change the markdown to .rst, couldnt
finish it though.<br>
<br>
<div>
<div><br>
</div>
</div>
</div>
<div class="gmail_extra"><br clear="all">
<div>
<div class="gmail_signature" data-smartmail="gmail_signature">
<div dir="ltr">
<div>--Humble<br>
</div>
<br>
</div>
</div>
</div>
<br>
<div class="gmail_quote">On Tue, Aug 16, 2016 at 9:34 AM,
Prashanth Pai <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:ppai@redhat.com" target="_blank">ppai@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="HOEnZb">
<div class="h5"><br>
<br>
----- Original Message -----<br>
> From: "Amye Scavarda" <<a moz-do-not-send="true"
href="mailto:amye@redhat.com">amye@redhat.com</a>><br>
> To: "Niels de Vos" <<a moz-do-not-send="true"
href="mailto:ndevos@redhat.com">ndevos@redhat.com</a>>,
"Humble Chirammal" <<a moz-do-not-send="true"
href="mailto:hchiramm@redhat.com">hchiramm@redhat.com</a>>,
"Prashanth Pai" <<a moz-do-not-send="true"
href="mailto:ppai@redhat.com">ppai@redhat.com</a>><br>
> Cc: "Amye Scavarda" <<a moz-do-not-send="true"
href="mailto:amye@redhat.com">amye@redhat.com</a>>,
"Gluster Devel" <<a moz-do-not-send="true"
href="mailto:gluster-devel@gluster.org">gluster-devel@gluster.org</a>><br>
> Sent: Monday, 15 August, 2016 10:45:59 PM<br>
> Subject: Re: [Gluster-devel] [gluster-devel]
Documentation Tooling Review<br>
><br>
> On Sat, Aug 13, 2016 at 12:23 AM, Niels de Vos <<a
moz-do-not-send="true" href="mailto:ndevos@redhat.com"><a class="moz-txt-link-abbreviated" href="mailto:ndevos@redhat.com">ndevos@redhat.com</a></a>>
wrote:<br>
><br>
> > On Thu, Aug 11, 2016 at 01:23:43PM -0700, Amye
Scavarda wrote:<br>
> > > The Red Hat Gluster Storage documentation
team and I had a conversation<br>
> > > about how we can our upstream
documentation more consistent and improved<br>
> > > for our users, and they're willing to
work with us to find where the<br>
> > major<br>
> > > gaps are in our documentation. This is
awesome! But it's going to take<br>
> > some<br>
> > > work on our side to make this a reality.<br>
> > ><br>
> > > One piece that's come up is that we
should probably look towards changing<br>
> > > current tooling for this. It turns out
that our ReadTheDocs instance<br>
> > search<br>
> > > is failing because we're using markdown,
and this is a known issue. It<br>
> > > doesn't look like it's going to be fixed
anytime soon.<br>
> > ><br>
> > > Rather than continue to try to make RTD
serve our needs, I'd like to<br>
> > > propose the following changes to where
our documentation lives and in<br>
> > what<br>
> > > language:<br>
> > > I'd much rather pattern after <a
moz-do-not-send="true"
href="http://docs.openshift.org" rel="noreferrer"
target="_blank">docs.openshift.org</a>, move to
ASCIIdoc and<br>
> > use<br>
> > > ASCIIbinder as our engine to power this.
What that does is give us<br>
> > control<br>
> > > over our overall infrastructure
underneath our documentation, maintain<br>
> > our<br>
> > > existing git workflow for adding to
documentation, and matches with other<br>
> > > communities that we work closely with.
I'm mindful that there's a burden<br>
> > of<br>
> > > migration again, but we'll be able to
resolve a lot of the challenges we<br>
> > > have with documentation currently: more
control over layout, ability to<br>
> > > change the structure to make it more user
friendly, use our own search<br>
> > > however we see fit.<br>
> > ><br>
> > > I'm happy to take comments on this
proposal. Over the next week, I'll be<br>
> > > reviewing the level of effort it would
take to migrate to ASCIIdocs and<br>
> > > ASCIIbinder, with the goal being to have
this in place by end of<br>
> > September.<br>
> ><br>
> > Sounds like a plan to me. I'm not sure how
much you have discussed this<br>
> > with the current doc maintainers, I think
there is some restructuring of<br>
> > the contents going on as well. It would be a
shame if that is lost in<br>
> > the process.<br>
> ><br>
> > Adding Humble and Prasanth here I as I'm not
sure what this restructuring<br>
> movement is?<br>
<br>
</div>
</div>
We've tried moving parts of documentation to .rst from
markdown to check it out<br>
as we waited far too long for an update from RTD folks and
from Red Hat<br>
documentation team.<br>
<br>
But hey this is good news that Red Hat documentation team is
contributing<br>
and hopefully user documentation woes will end soon.<br>
<span class="im HOEnZb"><br>
><br>
><br>
> Thanks!<br>
> - amye<br>
><br>
><br>
> > Could you (or one of the other doc maintainers)
give a talk/demo at the<br>
> > Gluster Summit about the process of contributing
to the documentation? I<br>
> > have the feeling only very few people are aware
how to send<br>
> > documentation changes.<br>
> ><br>
> > Thanks,<br>
> > Niels<br>
> ><br>
><br>
><br>
><br>
> --<br>
> Amye Scavarda | <a moz-do-not-send="true"
href="mailto:amye@redhat.com">amye@redhat.com</a> |
Gluster Community Lead<br>
><br>
</span>
<div class="HOEnZb">
<div class="h5">______________________________<wbr>_________________<br>
Gluster-devel mailing list<br>
<a moz-do-not-send="true"
href="mailto:Gluster-devel@gluster.org">Gluster-devel@gluster.org</a><br>
<a moz-do-not-send="true"
href="http://www.gluster.org/mailman/listinfo/gluster-devel"
rel="noreferrer" target="_blank">http://www.gluster.org/<wbr>mailman/listinfo/gluster-devel</a><br>
</div>
</div>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Gluster-devel mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Gluster-devel@gluster.org">Gluster-devel@gluster.org</a>
<a class="moz-txt-link-freetext" href="http://www.gluster.org/mailman/listinfo/gluster-devel">http://www.gluster.org/mailman/listinfo/gluster-devel</a></pre>
</blockquote>
<br>
</body>
</html>