On 11 Aug 2016, at 21:23, Amye Scavarda <amye at redhat.com> wrote: > The Red Hat Gluster Storage documentation team and I had a conversation > about how we can our upstream documentation more consistent and improved > for our users, and they're willing to work with us to find where the major > gaps are in our documentation. This is awesome! But it's going to take some > work on our side to make this a reality. > > One piece that's come up is that we should probably look towards changing > current tooling for this. It turns out that our ReadTheDocs instance search > is failing because we're using markdown, and this is a known issue. It > doesn't look like it's going to be fixed anytime soon. > > Rather than continue to try to make RTD serve our needs, I'd like to > propose the following changes to where our documentation lives and in what > language: > I'd much rather pattern after docs.openshift.org, move to ASCIIdoc and use > ASCIIbinder as our engine to power this. What that does is give us control > over our overall infrastructure underneath our documentation, maintain our > existing git workflow for adding to documentation, and matches with other > communities that we work closely with. I'm mindful that there's a burden of > migration again, but we'll be able to resolve a lot of the challenges we > have with documentation currently: more control over layout, ability to > change the structure to make it more user friendly, use our own search > however we see fit. > > I'm happy to take comments on this proposal. Over the next week, I'll be > reviewing the level of effort it would take to migrate to ASCIIdocs and > ASCIIbinder, with the goal being to have this in place by end of September. > > Thoughts? It's probably worth considering GitBook instead: https://www.gitbook.com Example here: http://tutorial.djangogirls.org/en/index.html Pros: * Works with Markdown & ASCIIdoc No need to convert the existing docs to a new format, and the already learned Markdown skills don't need relearning * Also fully Open Source https://github.com/GitbookIO/gitbook/ * Searching works very well Try searching on the Django Girls tutorial above for "Python". Correct results are returned in small fractions of a second. * Has well developed plugins to enable things like inline videos, interactive exercises (and more) https://plugins.gitbook.com * Can be self hosted, or hosted on the GitBooks infrastructure * Doesn't require Ruby, unlike ASCIIbinder which is written in it. Cons: * It's written in Node.js instead Not sure that's any better than Ruby It seems a better polished solution than docs.openshift.org is using, and would probably require less effort for the Gluster docs to be adapted to. Thoughts? :) + Justin -- "My grandfather once told me that there are two kinds of people: those who work and those who take the credit. He told me to try to be in the first group; there was less competition there." - Indira Gandhi _______________________________________________ Gluster-devel mailing list Gluster-devel@xxxxxxxxxxx http://www.gluster.org/mailman/listinfo/gluster-devel
