<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Aug 23, 2016 at 4:42 PM, Joe Julian <span dir="ltr"><<a href="mailto:joe@julianfamily.org" target="_blank">joe@julianfamily.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><br>
<br>
On 08/23/2016 12:27 PM, Justin Clift wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
On 11 Aug 2016, at 21:23, Amye Scavarda <amye at <a href="http://redhat.com" rel="noreferrer" target="_blank">redhat.com</a>> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
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 major<br>
gaps are in our documentation. This is awesome! But it's going to take 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 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 what<br>
language:<br>
I'd much rather pattern after <a href="http://docs.openshift.org" rel="noreferrer" target="_blank">docs.openshift.org</a>, move to ASCIIdoc and use<br>
ASCIIbinder as our engine to power this. What that does is give us control<br>
over our overall infrastructure underneath our documentation, maintain 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 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 September.<br>
<br>
Thoughts?<br>
</blockquote>
It's probably worth considering GitBook instead:<br>
<br>
<a href="https://www.gitbook.com" rel="noreferrer" target="_blank">https://www.gitbook.com</a><br>
<br>
Example here:<br>
<br>
<a href="http://tutorial.djangogirls.org/en/index.html" rel="noreferrer" target="_blank">http://tutorial.djangogirls.o<wbr>rg/en/index.html</a><br>
<br>
Pros:<br>
<br>
* Works with Markdown & ASCIIdoc<br>
<br>
No need to convert the existing docs to a new format,<br>
and the already learned Markdown skills don't need relearning<br>
<br>
* Also fully Open Source<br>
<br>
<a href="https://github.com/GitbookIO/gitbook/" rel="noreferrer" target="_blank">https://github.com/GitbookIO/<wbr>gitbook/</a><br>
<br>
* Searching works very well<br>
<br>
Try searching on the Django Girls tutorial above for "Python".<br>
<br>
Correct results are returned in small fractions of a second.<br>
<br>
* Has well developed plugins to enable things like inline<br>
videos, interactive exercises (and more)<br>
<br>
<a href="https://plugins.gitbook.com" rel="noreferrer" target="_blank">https://plugins.gitbook.com</a><br>
<br>
* Can be self hosted, or hosted on the GitBooks infrastructure<br>
<br>
* Doesn't require Ruby, unlike ASCIIbinder which is written<br>
in it.<br>
<br>
Cons:<br>
<br>
* It's written in Node.js instead<br>
<br>
Not sure that's any better than Ruby<br>
<br>
It seems a better polished solution than <a href="http://docs.openshift.org" rel="noreferrer" target="_blank">docs.openshift.org</a> is using,<br>
and would probably require less effort for the Gluster docs to be adapted<br>
to.<br>
<br>
Thoughts? :)<br>
<br>
+ Justin<br>
<br>
</blockquote></div></div>
+1 This seems like the most sane solution<div><div><br>
______________________________<wbr>_________________<br>
Gluster-devel mailing list<br>
<a href="mailto:Gluster-devel@gluster.org" target="_blank">Gluster-devel@gluster.org</a><br>
<a href="http://www.gluster.org/mailman/listinfo/gluster-devel" rel="noreferrer" target="_blank">http://www.gluster.org/mailman<wbr>/listinfo/gluster-devel</a><br>
</div></div></blockquote></div><div class="gmail_extra"><br></div></div><div class="gmail_extra">I'll jump back in here: </div><div class="gmail_extra"><a href="https://github.com/gluster/glusterdocs/pulse/monthly" target="_blank">https://github.com/gluster/<wbr>glusterdocs/pulse/monthly</a> shows not a ton of activity currently, as Humble pointed to earlier. That's not a bad thing, but this may speak to Niels' point that contributing to Docs isn't something that's currently well known. </div><div class="gmail_extra"><br></div><div class="gmail_extra">My sense is that we should separate this into two different conversations: improving the user + admin guides with contributions from the Red Hat Gluster Storage team, and the second conversation about how we take developer contribution. That gets Gluster.org back to a place where we can contribute the developer guides with what's under active development. </div><div class="gmail_extra"><br></div><div class="gmail_extra">Unfortunately, the tooling part is where we start with this, because the contribution of the actively maintained documentation also depends on ascii. As soon as I have a link to a proof of concept for what ASCIIdocs + asciibinder could look like, I'll post it here for review. </div><div class="gmail_extra"><br></div><div class="gmail_extra">My goal in pushing this is to get us to a place where we're contributing the things that we know best, the features we're actively working on, and how to help contribute to the project, while using the resources we have to improve the user experience. </div><div class="gmail_extra"> </div><div class="gmail_extra">-- <br><div><div dir="ltr">Amye Scavarda | <a href="mailto:amye@redhat.com" target="_blank">amye@redhat.com</a> | Gluster Community Lead</div></div>
</div></div>