On 23 Aug 2016, at 20:27, Justin Clift <justin@xxxxxxxxxxxxxx> wrote: > 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. An extra "Pro" pointed out to me offline: * You can log in with GitHub and post comments on each line Example here: https://docs.lacona.io/docs/basics/getting-started.html Note the green line there, with a helpful comment added to the side of that Seems like a good way for people to review/revise docs, for polishing & tweaking. > 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
