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

Tue Aug 16 06:12:02 UTC 2016

Hi Amye,

If I am not mistaken, the RTD search is broken with mkdocs theme in their
hosted ( <project.RTD.{org/io}) platform. iic, Its also possible that we
can  host RTD in house and maintain it.  It gives us the freedom of using
the same markdown files with a different theme or customization or some
workaround for the search issue. It looks to me that, this is what @Gandalf
is trying to propose in earlier threads.

Its indeed a good move to have  more people to contribute  to our upstream
documentation. But it has to be weighed against the existing data. If its
going to be continuous help Red Hat documentation team to improve our
documentation, instead of one shot attempt,  we can definitely think about
it. Also, we need acknowledge from the community to shift our documentation
format from Markdown to ASCIIdoc or something else, which we are trying to
figure it out from this thread.

@Niels, I would like to defend your thought  " I have the feeling only very
few people are aware how to send documentation changes",  based on
https://github.com/gluster/glusterdocs/graphs/contributors :) .

Also, as Prasanth mentioned, when the RTD search issue was unresolved we
gave a try to change the markdown to .rst, couldnt finish it though.

--Humble

On Tue, Aug 16, 2016 at 9:34 AM, Prashanth Pai <ppai at redhat.com> wrote:

>
>
> ----- Original Message -----
> > From: "Amye Scavarda" <amye at redhat.com>
> > To: "Niels de Vos" <ndevos at redhat.com>, "Humble Chirammal" <
> hchiramm at redhat.com>, "Prashanth Pai" <ppai at redhat.com>
> > Cc: "Amye Scavarda" <amye at redhat.com>, "Gluster Devel" <
> gluster-devel at gluster.org>
> > Sent: Monday, 15 August, 2016 10:45:59 PM
> > Subject: Re: [Gluster-devel] [gluster-devel] Documentation Tooling Review
> >
> > 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?
>
> We've tried moving parts of documentation to .rst from markdown to check
> it out
> as we waited far too long for an update from RTD folks and from Red Hat
> documentation team.
>
> But hey this is good news that Red Hat documentation team is contributing
> and hopefully user documentation woes will end soon.
>
> >
> >
> > 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
> >
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-devel/attachments/20160816/35e2c405/attachment.html>