[Gluster-devel] [gluster-devel] Documentation Tooling Review

[Joe Julian]

On 08/23/2016 12:27 PM, Justin Clift 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.
>
> 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
>
+1 This seems like the most sane solution