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

2016-09-23 Thread Rajesh Joseph 
On Thu, Sep 22, 2016 at 10:05 PM, Gandalf Corvotempesta <
gandalf.corvotempe...@gmail.com> wrote:

> 2016-09-22 18:34 GMT+02:00 Amye Scavarda :
> > Nope! RHGS is the supported version and gluster.org is the open source
> > version. We'd like to keep the documentation reflecting that, but good
> > catch.
>
> Ok but features should be the same, right?
>

Yes, features would be same, infact upstream would be ahead of RHGS.
Similarly our upstream documentation will be ahead of Red Hat documentation.

I should have been more clear. In Red Hat documentation there are lot of
references to version specific changes which will not be applicable to
Gluster releases. Also there is branding difference Red Hat like to call
the product "Red Hat Gluster Storage" (RHGS) and we "Gluster"

-Rajesh
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-09-22 Thread Gandalf Corvotempesta 
2016-09-22 18:34 GMT+02:00 Amye Scavarda :
> Nope! RHGS is the supported version and gluster.org is the open source
> version. We'd like to keep the documentation reflecting that, but good
> catch.

Ok but features should be the same, right?
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-09-22 Thread Amye Scavarda 
On Thu, Sep 22, 2016 at 9:31 AM, Gandalf Corvotempesta <
gandalf.corvotempe...@gmail.com> wrote:

> 2016-09-22 17:25 GMT+02:00 Rajesh Joseph :
>>
>> I merged our upstream documenation with the Red Hat documentation and
>> removed
>> few Red Hat specific contents.
>>
>> Which content is RH specific? Aren't gluster and RHGS the same ?
>
>
Nope! RHGS is the supported version and gluster.org is the open source
version. We'd like to keep the documentation reflecting that, but good
catch.
- amye

-- 
Amye Scavarda | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-09-22 Thread Gandalf Corvotempesta 
2016-09-22 17:25 GMT+02:00 Rajesh Joseph :
>
> I merged our upstream documenation with the Red Hat documentation and
> removed
> few Red Hat specific contents.
>
> Which content is RH specific? Aren't gluster and RHGS the same ?
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-09-22 Thread Rajesh Joseph 
On Thu, Sep 8, 2016 at 5:00 AM, Amye Scavarda  wrote:

>
>
> On Tue, Aug 23, 2016 at 4:42 PM, Joe Julian  wrote:
>
>>
>>
>> On 08/23/2016 12:27 PM, Justin Clift wrote:
>>
>>> On 11 Aug 2016, at 21:23, 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.

 Thoughts?

>>> It's probably worth considering GitBook instead:
>>>
>>>https://www.gitbook.com
>>>
>>> Example here:
>>>
>>>http://tutorial.djangogirls.org/en/index.html
>>>
>>> Pros:
>>>
>>>* Works with Markdown & ASCIIdoc
>>>
>>>  No need to convert the existing docs to a new format,
>>>  and the already learned Markdown skills don't need relearning
>>>
>>>* Also fully Open Source
>>>
>>>  https://github.com/GitbookIO/gitbook/
>>>
>>>* Searching works very well
>>>
>>>  Try searching on the Django Girls tutorial above for "Python".
>>>
>>>  Correct results are returned in small fractions of a second.
>>>
>>>* Has well developed plugins to enable things like inline
>>>  videos, interactive exercises (and more)
>>>
>>>  https://plugins.gitbook.com
>>>
>>>* Can be self hosted, or hosted on the GitBooks infrastructure
>>>
>>>* Doesn't require Ruby, unlike ASCIIbinder which is written
>>>  in it.
>>>
>>> Cons:
>>>
>>>* It's written in Node.js instead
>>>
>>>  Not sure that's any better than Ruby
>>>
>>> It seems a better polished solution than docs.openshift.org is using,
>>> and would probably require less effort for the Gluster docs to be adapted
>>> to.
>>>
>>> Thoughts? :)
>>>
>>> + Justin
>>>
>>> +1 This seems like the most sane solution
>>
>> ___
>> Gluster-devel mailing list
>> Gluster-devel@gluster.org
>> http://www.gluster.org/mailman/listinfo/gluster-devel
>>
>
> I'll jump back in here:
> https://github.com/gluster/glusterdocs/pulse/monthly shows not a ton of
> activity currently, as Humble pointed to earlier. That's not a bad thing,
> but this may speak to Niels' point that contributing to Docs isn't
> something that's currently well known.
>
> My sense is that we should separate this into two different conversations:
> improving the user + admin guides with contributions from the Red Hat
> Gluster Storage team, and the second conversation about how we take
> developer contribution. That gets Gluster.org back to a place where we can
> contribute the developer guides with what's under active development.
>
> Unfortunately, the tooling part is where we start with this, because the
> contribution of the actively maintained documentation also depends on
> ascii. As soon as I have a link to a proof of concept for what ASCIIdocs +
> asciibinder could look like, I'll post it here for review.
>
> My goal in pushing this is to get us to a place where we're contributing
> the things that we know best, the features we're actively working on, and
> how to help contribute to the project, while using the resources we have to
> improve the user experience.
>
> --
> Amye Scavarda | a...@redhat.com | Gluster Community Lead
>
> ___
> Gluster-devel mailing list
> Gluster-devel@gluster.org
>

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

2016-08-23 Thread Joe Julian 



On 08/23/2016 12:27 PM, Justin Clift wrote:

On 11 Aug 2016, at 21:23, 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.

Thoughts?

It's probably worth considering GitBook instead:

   https://www.gitbook.com

Example here:

   http://tutorial.djangogirls.org/en/index.html

Pros:

   * Works with Markdown & ASCIIdoc

 No need to convert the existing docs to a new format,
 and the already learned Markdown skills don't need relearning

   * Also fully Open Source

 https://github.com/GitbookIO/gitbook/

   * Searching works very well

 Try searching on the Django Girls tutorial above for "Python".

 Correct results are returned in small fractions of a second.

   * Has well developed plugins to enable things like inline
 videos, interactive exercises (and more)

 https://plugins.gitbook.com

   * Can be self hosted, or hosted on the GitBooks infrastructure

   * Doesn't require Ruby, unlike ASCIIbinder which is written
 in it.

Cons:

   * It's written in Node.js instead

 Not sure that's any better than Ruby

It seems a better polished solution than docs.openshift.org is using,
and would probably require less effort for the Gluster docs to be adapted
to.

Thoughts? :)

+ Justin


+1 This seems like the most sane solution
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-23 Thread Justin Clift 
On 23 Aug 2016, at 20:27, Justin Clift  wrote:
> On 11 Aug 2016, at 21:23, 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.
>> 
>> Thoughts?
> 
> It's probably worth considering GitBook instead:
> 
>  https://www.gitbook.com
> 
> Example here:
> 
>  http://tutorial.djangogirls.org/en/index.html
> 
> Pros:
> 
>  * Works with Markdown & ASCIIdoc
> 
>No need to convert the existing docs to a new format,
>and the already learned Markdown skills don't need relearning
> 
>  * Also fully Open Source
> 
>https://github.com/GitbookIO/gitbook/
> 
>  * Searching works very well
> 
>Try searching on the Django Girls tutorial above for "Python".
> 
>Correct results are returned in small fractions of a second.
> 
>  * Has well developed plugins to enable things like inline
>videos, interactive exercises (and more)
> 
>https://plugins.gitbook.com
> 
>  * Can be self hosted, or hosted on the GitBooks infrastructure
> 
>  * Doesn't require Ruby, unlike ASCIIbinder which is written
>in it.

An extra "Pro" pointed out to me offline:

  * You can log in with GitHub and post comments on each line

Example here:

  https://docs.lacona.io/docs/basics/getting-started.html

Note the green line there, with a helpful comment added to the
side of that

Seems like a good way for people to review/revise docs, for polishing
& tweaking.



> Cons:
> 
>  * It's written in Node.js instead
> 
>Not sure that's any better than Ruby
> 
> It seems a better polished solution than docs.openshift.org is using,
> and would probably require less effort for the Gluster docs to be adapted
> to.
> 
> Thoughts? :)

+ Justin

--
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
- Indira Gandhi

___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-23 Thread Justin Clift 
On 11 Aug 2016, at 21:23, 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.
> 
> Thoughts?

It's probably worth considering GitBook instead:

  https://www.gitbook.com

Example here:

  http://tutorial.djangogirls.org/en/index.html

Pros:

  * Works with Markdown & ASCIIdoc

No need to convert the existing docs to a new format,
and the already learned Markdown skills don't need relearning

  * Also fully Open Source

https://github.com/GitbookIO/gitbook/

  * Searching works very well

Try searching on the Django Girls tutorial above for "Python".

Correct results are returned in small fractions of a second.

  * Has well developed plugins to enable things like inline
videos, interactive exercises (and more)

https://plugins.gitbook.com

  * Can be self hosted, or hosted on the GitBooks infrastructure

  * Doesn't require Ruby, unlike ASCIIbinder which is written
in it.

Cons:

  * It's written in Node.js instead

Not sure that's any better than Ruby

It seems a better polished solution than docs.openshift.org is using,
and would probably require less effort for the Gluster docs to be adapted
to.

Thoughts? :)

+ Justin

--
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
- Indira Gandhi

___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-16 Thread Saravanakumar Arumugam 


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 <p...@redhat.com 
<mailto:p...@redhat.com>> wrote:




- Original Message -
> From: "Amye Scavarda" <a...@redhat.com <mailto:a...@redhat.com>>
> To: "Niels de Vos" <nde...@redhat.com
<mailto:nde...@redhat.com>>, "Humble Chirammal"
<hchir...@redhat.com <mailto:hchir...@redhat.com>>, "Prashanth
Pai" <p...@redhat.com <mailto:p...@redhat.com>>
> Cc: "Amye Scavarda" <a...@redhat.com <mailto:a...@redhat.com>>,
"Gluster Devel" <gluster-devel@gluster.org
<mailto:gluster-devel@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
<nde...@redhat.com <mailto:nde...@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

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

2016-08-15 Thread Prashanth Pai 


- Original Message -
> From: "Amye Scavarda" <a...@redhat.com>
> To: "Niels de Vos" <nde...@redhat.com>, "Humble Chirammal" 
> <hchir...@redhat.com>, "Prashanth Pai" <p...@redhat.com>
> Cc: "Amye Scavarda" <a...@redhat.com>, "Gluster Devel" 
> <gluster-devel@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 <nde...@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 | a...@redhat.com | Gluster Community Lead
> 
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-15 Thread Amye Scavarda 
On Sat, Aug 13, 2016 at 12:23 AM, Niels de Vos  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 | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-15 Thread Amye Scavarda 
On Mon, Aug 15, 2016 at 9:49 AM, Gandalf Corvotempesta <
gandalf.corvotempe...@gmail.com> wrote:

> Il 15 ago 2016 18:32, "Amye Scavarda"  ha scritto:
> >
> > I'm not sure what you're proposing here?
> >>
>
> I'm proposing to not move current docs from markdown to asciidoc (that
> means to rewrite everithing) but just change read the docs with something
> else
>
> If read the docs is the main issue, just change that and not also the docs
> format.
>
I think that's a much bigger task than it looks like, but I'll let someone
closer to the actual infrastructure weigh in on that.



-- 
Amye Scavarda | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-15 Thread Gandalf Corvotempesta 
Il 15 ago 2016 18:32, "Amye Scavarda"  ha scritto:
>
> I'm not sure what you're proposing here?
>>

I'm proposing to not move current docs from markdown to asciidoc (that
means to rewrite everithing) but just change read the docs with something
else

If read the docs is the main issue, just change that and not also the docs
format.
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-15 Thread Amye Scavarda 
On Sat, Aug 13, 2016 at 1:22 AM, Gandalf Corvotempesta <
gandalf.corvotempe...@gmail.com> wrote:

> Il 13 ago 2016 1:18 AM, "Amye Scavarda"  ha scritto:
> > 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
>
> If main issue is the RTD broken search,  why rewrote the whole docs moving
> from markdown to asciidoc?
> Just change RTD with something else and still keep using the current
> markdown pages
>

I'm not sure what you're proposing here?

> Much faster and easier, and you don't have to rewrite everything.
>
Thanks!


-- 
Amye Scavarda | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-13 Thread Gandalf Corvotempesta 
Il 13 ago 2016 1:18 AM, "Amye Scavarda"  ha scritto:
> 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

If main issue is the RTD broken search,  why rewrote the whole docs moving
from markdown to asciidoc?
Just change RTD with something else and still keep using the current
markdown pages

Much faster and easier, and you don't have to rewrite everything.
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-13 Thread Niels de Vos 
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.

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


signature.asc
Description: PGP signature
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-12 Thread Sankarshan Mukhopadhyay 
On Fri, Aug 12, 2016 at 1:53 AM, Amye Scavarda  wrote:

[snip]

> 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.

This is a good start.


-- 
sankarshan mukhopadhyay

___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-12 Thread Amye Scavarda 
On Thu, Aug 11, 2016 at 1:23 PM, 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.
>
> 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 | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

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

2016-08-11 Thread Amye Scavarda 
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

-- 
Amye Scavarda | a...@redhat.com | Gluster Community Lead
___
Gluster-devel mailing list
Gluster-devel@gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel