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

[Amye Scavarda]

On Sat, Aug 13, 2016 at 12:23 AM, Niels de Vos <ndevos at redhat.com> wrote:

> On Thu, Aug 11, 2016 at 01:23:43PM -0700, Amye Scavarda 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.
>
> Sounds like a plan to me. I'm not sure how much you have discussed this
> with the current doc maintainers, I think there is some restructuring of
> the contents going on as well. It would be a shame if that is lost in
> the process.
>
> Adding Humble and Prasanth here I as I'm not sure what this restructuring
movement is?


Thanks!
- amye


> Could you (or one of the other doc maintainers) give a talk/demo at the
> Gluster Summit about the process of contributing to the documentation? I
> have the feeling only very few people are aware how to send
> documentation changes.
>
> Thanks,
> Niels
>



-- 
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/20160815/8e43f340/attachment-0001.html>