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 <[email protected]
<mailto:[email protected]>> wrote:
----- Original Message -----
> From: "Amye Scavarda" <[email protected] <mailto:[email protected]>>
> To: "Niels de Vos" <[email protected]
<mailto:[email protected]>>, "Humble Chirammal"
<[email protected] <mailto:[email protected]>>, "Prashanth
Pai" <[email protected] <mailto:[email protected]>>
> Cc: "Amye Scavarda" <[email protected] <mailto:[email protected]>>,
"Gluster Devel" <[email protected]
<mailto:[email protected]>>
> 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
<[email protected] <mailto:[email protected]>> 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 | [email protected] <mailto:[email protected]> |
Gluster Community Lead
>
_______________________________________________
Gluster-devel mailing list
[email protected] <mailto:[email protected]>
http://www.gluster.org/mailman/listinfo/gluster-devel
<http://www.gluster.org/mailman/listinfo/gluster-devel>
_______________________________________________
Gluster-devel mailing list
[email protected]
http://www.gluster.org/mailman/listinfo/gluster-devel
_______________________________________________
Gluster-devel mailing list
[email protected]
http://www.gluster.org/mailman/listinfo/gluster-devel
