[Gluster-devel] [gluster-devel] Documentation Tooling Review
Saravanakumar Arumugam
sarumuga at redhat.com
Tue Aug 16 07:58:19 UTC 2016
On 08/16/2016 11:42 AM, Humble Devassy Chirammal wrote:
> 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.
+1
From the user perspective, changing the gluster documentation (again)
to a different format is going to be painful.
People used to bookmark a link, when they visit and resolve a issue.
If user is going to get 404 for these links, I think it's bad.
We should strive to resolve issues with existing links.
I can see many readthedocs website where search functionality is working
fine..maybe we should first try what Humble suggested here.
> 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
> <mailto:ppai at redhat.com>> wrote:
>
>
>
> ----- Original Message -----
> > From: "Amye Scavarda" <amye at redhat.com <mailto:amye at redhat.com>>
> > To: "Niels de Vos" <ndevos at redhat.com
> <mailto:ndevos at redhat.com>>, "Humble Chirammal"
> <hchiramm at redhat.com <mailto:hchiramm at redhat.com>>, "Prashanth
> Pai" <ppai at redhat.com <mailto:ppai at redhat.com>>
> > Cc: "Amye Scavarda" <amye at redhat.com <mailto:amye at redhat.com>>,
> "Gluster Devel" <gluster-devel at gluster.org
> <mailto: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 <mailto: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
> <http://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 <mailto:amye at redhat.com> |
> Gluster Community Lead
> >
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at gluster.org <mailto:Gluster-devel at gluster.org>
> http://www.gluster.org/mailman/listinfo/gluster-devel
> <http://www.gluster.org/mailman/listinfo/gluster-devel>
>
>
>
>
> _______________________________________________
> 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/601d76d3/attachment-0001.html>
More information about the Gluster-devel
mailing list