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
_______________________________________________
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel
