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

[Amye Scavarda]

On Thu, Aug 11, 2016 at 1:23 PM, 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?
> - amye
>
> Pushing this one higher again to see if anyone has objections to looking
more into ASCIIdocs.
Our RTD search issue is a known issue and not likely to be resolved in the
RTD platform.
- amye

-- 
Amye Scavarda | amye at redhat.com | Gluster Community Lead
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-devel/attachments/20160812/b42ba376/attachment.html>