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

[Justin Clift]

On 23 Aug 2016, at 20:27, Justin Clift <justin at postgresql.org> 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