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

[Justin Clift]

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