Documentation by contributors

[Raul Kripalani-2]

I believe that the current contribution process does not require
contributors to enhance/modify the user guide accordingly.

Do you think it would make sense to add this as a requirement to the
process?

Or are committers willing to take care of these docs in their entirety?
Usually it's most efficient to have the contributor document their own
feature/enhancement.

We could use readme.io collaboration functionalities to Suggest Edits.

Raúl.

[Alexey Kuznetsov-2]

I think contributor should provide at least some text file with a feature
description.
But collaboration on readme.io is a better approach.
I don't know it is possible to introduce new topics on readme.io?
I know that it is possible to suggest "changes".
We could have a special "landing page" for new items from contributors in
this case.

On Wed, Aug 26, 2015 at 3:39 PM, Raul Kripalani <[hidden email]> wrote:

> I believe that the current contribution process does not require
> contributors to enhance/modify the user guide accordingly.
>
> Do you think it would make sense to add this as a requirement to the
> process?
>
> Or are committers willing to take care of these docs in their entirety?
> Usually it's most efficient to have the contributor document their own
> feature/enhancement.
>
> We could use readme.io collaboration functionalities to Suggest Edits.
>
> Raúl.
>

--
Alexey Kuznetsov
GridGain Systems
www.gridgain.com

[Sergi]

AFAIK currently "Suggest Edit" works well on readme.io.
If someone wants to introduce a new topic, he can ask someone to do that on
dev/user lists.

Sergi

2015-08-26 14:09 GMT+03:00 Alexey Kuznetsov <[hidden email]>:

> I think contributor should provide at least some text file with a feature
> description.
> But collaboration on readme.io is a better approach.
> I don't know it is possible to introduce new topics on readme.io?
> I know that it is possible to suggest "changes".
> We could have a special "landing page" for new items from contributors in
> this case.
>
> On Wed, Aug 26, 2015 at 3:39 PM, Raul Kripalani <[hidden email]> wrote:
>
> > I believe that the current contribution process does not require
> > contributors to enhance/modify the user guide accordingly.
> >
> > Do you think it would make sense to add this as a requirement to the
> > process?
> >
> > Or are committers willing to take care of these docs in their entirety?
> > Usually it's most efficient to have the contributor document their own
> > feature/enhancement.
> >
> > We could use readme.io collaboration functionalities to Suggest Edits.
> >
> > Raúl.
> >
>
>
>
> --
> Alexey Kuznetsov
> GridGain Systems
> www.gridgain.com
>

[Konstantin Boudnik-2]

Just as a friendly reminder: readme.io hosting still opens us to the issue we've been
discussing at length. Namely - the source of the documentation isn't hosted on
the Apache premises. I remember there were some conversations with readme.io
folks to add some extras for the imports or something like that. Were there
any follow-ups on that front?

Sorry if I missed anything.
  Cos

On Wed, Aug 26, 2015 at 04:43PM, Sergi Vladykin wrote:

> AFAIK currently "Suggest Edit" works well on readme.io.
> If someone wants to introduce a new topic, he can ask someone to do that on
> dev/user lists.
>
> Sergi
>
> 2015-08-26 14:09 GMT+03:00 Alexey Kuznetsov <[hidden email]>:
>
> > I think contributor should provide at least some text file with a feature
> > description.
> > But collaboration on readme.io is a better approach.
> > I don't know it is possible to introduce new topics on readme.io?
> > I know that it is possible to suggest "changes".
> > We could have a special "landing page" for new items from contributors in
> > this case.
> >
> > On Wed, Aug 26, 2015 at 3:39 PM, Raul Kripalani <[hidden email]> wrote:
> >
> > > I believe that the current contribution process does not require
> > > contributors to enhance/modify the user guide accordingly.
> > >
> > > Do you think it would make sense to add this as a requirement to the
> > > process?
> > >
> > > Or are committers willing to take care of these docs in their entirety?
> > > Usually it's most efficient to have the contributor document their own
> > > feature/enhancement.
> > >
> > > We could use readme.io collaboration functionalities to Suggest Edits.
> > >
> > > Raúl.
> > >
> >
> >
> >
> > --
> > Alexey Kuznetsov
> > GridGain Systems
> > www.gridgain.com
> >

[dsetrakyan]

On Wed, Aug 26, 2015 at 8:44 PM, Konstantin Boudnik <[hidden email]> wrote:

> Just as a friendly reminder: readme.io hosting still opens us to the
> issue we've been
> discussing at length. Namely - the source of the documentation isn't
> hosted on
> the Apache premises. I remember there were some conversations with
> readme.io
> folks to add some extras for the imports or something like that. Were there
> any follow-ups on that front?
>

Cos, good point. I was actually going to start a thread about this.
Readme.io actually is replicated in GitHub with by-directional integration
here:

https://github.com/apacheignite/documentation

The only thing we need is to move this repository to Apache, with Readme
application having access to it. If there are no objections, I will start a
discussion with INFRA on this. Let me know your thoughts.

> Sorry if I missed anything.
>   Cos
>
> On Wed, Aug 26, 2015 at 04:43PM, Sergi Vladykin wrote:
> > AFAIK currently "Suggest Edit" works well on readme.io.
> > If someone wants to introduce a new topic, he can ask someone to do that
> on
> > dev/user lists.
> >
> > Sergi
> >
> > 2015-08-26 14:09 GMT+03:00 Alexey Kuznetsov <[hidden email]>:
> >
> > > I think contributor should provide at least some text file with a
> feature
> > > description.
> > > But collaboration on readme.io is a better approach.
> > > I don't know it is possible to introduce new topics on readme.io?
> > > I know that it is possible to suggest "changes".
> > > We could have a special "landing page" for new items from contributors
> in
> > > this case.
> > >
> > > On Wed, Aug 26, 2015 at 3:39 PM, Raul Kripalani <[hidden email]>
> wrote:
> > >
> > > > I believe that the current contribution process does not require
> > > > contributors to enhance/modify the user guide accordingly.
> > > >
> > > > Do you think it would make sense to add this as a requirement to the
> > > > process?
> > > >
> > > > Or are committers willing to take care of these docs in their
> entirety?
> > > > Usually it's most efficient to have the contributor document their
> own
> > > > feature/enhancement.
> > > >
> > > > We could use readme.io collaboration functionalities to Suggest
> Edits.
> > > >
> > > > Raúl.
> > > >
> > >
> > >
> > >
> > > --
> > > Alexey Kuznetsov
> > > GridGain Systems
> > > www.gridgain.com
> > >
>

[Konstantin Boudnik-2]

On Wed, Aug 26, 2015 at 09:07PM, Dmitriy Setrakyan wrote:

> On Wed, Aug 26, 2015 at 8:44 PM, Konstantin Boudnik <[hidden email]> wrote:
>
> > Just as a friendly reminder: readme.io hosting still opens us to the
> > issue we've been
> > discussing at length. Namely - the source of the documentation isn't
> > hosted on
> > the Apache premises. I remember there were some conversations with
> > readme.io
> > folks to add some extras for the imports or something like that. Were there
> > any follow-ups on that front?
> >
>
> Cos, good point. I was actually going to start a thread about this.
> Readme.io actually is replicated in GitHub with by-directional integration
> here:
>
> https://github.com/apacheignite/documentation
>
> The only thing we need is to move this repository to Apache, with Readme
> application having access to it. If there are no objections, I will start a
> discussion with INFRA on this. Let me know your thoughts.

this 'documentation' repo is the official project documentation, as far as I
remember? If so - yes, let's move it to Apache git. Also, I don't see a reason
to keep it separated from the rest of the source code - it's a part of the
project. And it would be easier to track the documentation relevance to the
releases if they are together, IMO.

If we were to keep it within the project repo, there's no need to involve
INFRA into this - let's just import it and be done with it.

Cos

[dsetrakyan]

On Wed, Aug 26, 2015 at 9:15 PM, Konstantin Boudnik <[hidden email]> wrote:

> On Wed, Aug 26, 2015 at 09:07PM, Dmitriy Setrakyan wrote:
> > On Wed, Aug 26, 2015 at 8:44 PM, Konstantin Boudnik <[hidden email]>
> wrote:
> >
> > > Just as a friendly reminder: readme.io hosting still opens us to the
> > > issue we've been
> > > discussing at length. Namely - the source of the documentation isn't
> > > hosted on
> > > the Apache premises. I remember there were some conversations with
> > > readme.io
> > > folks to add some extras for the imports or something like that. Were
> there
> > > any follow-ups on that front?
> > >
> >
> > Cos, good point. I was actually going to start a thread about this.
> > Readme.io actually is replicated in GitHub with by-directional
> integration
> > here:
> >
> > https://github.com/apacheignite/documentation
> >
> > The only thing we need is to move this repository to Apache, with Readme
> > application having access to it. If there are no objections, I will
> start a
> > discussion with INFRA on this. Let me know your thoughts.
>
> this 'documentation' repo is the official project documentation, as far as
> I
> remember? If so - yes, let's move it to Apache git. Also, I don't see a
> reason to keep it separated from the rest of the source code - it's a part
> of the project. And it would be easier to track the documentation relevance
> to the releases if they are together, IMO.
>

I think it should be a separate repo, mainly because we probably should not
allow a 3rd party app have write privilege to our main repo. On top of
that, readme.io process has already been tested this way and it works (I
don't think there is a need to ask them to change it).

If we setup a new repo, do you think Apache GIT would allow an external
application to connect to it?


> If we were to keep it within the project repo, there's no need to involve
> INFRA into this - let's just import it and be done with it.
>
> Cos
>

[Branko Čibej]

On 26.08.2015 21:02, Dmitriy Setrakyan wrote:

> On Wed, Aug 26, 2015 at 9:15 PM, Konstantin Boudnik <[hidden email]> wrote:
>
>> On Wed, Aug 26, 2015 at 09:07PM, Dmitriy Setrakyan wrote:
>>> On Wed, Aug 26, 2015 at 8:44 PM, Konstantin Boudnik <[hidden email]>
>> wrote:
>>>> Just as a friendly reminder: readme.io hosting still opens us to the
>>>> issue we've been
>>>> discussing at length. Namely - the source of the documentation isn't
>>>> hosted on
>>>> the Apache premises. I remember there were some conversations with
>>>> readme.io
>>>> folks to add some extras for the imports or something like that. Were
>> there
>>>> any follow-ups on that front?
>>>>
>>> Cos, good point. I was actually going to start a thread about this.
>>> Readme.io actually is replicated in GitHub with by-directional
>> integration
>>> here:
>>>
>>> https://github.com/apacheignite/documentation
>>>
>>> The only thing we need is to move this repository to Apache, with Readme
>>> application having access to it. If there are no objections, I will
>> start a
>>> discussion with INFRA on this. Let me know your thoughts.
>> this 'documentation' repo is the official project documentation, as far as
>> I
>> remember? If so - yes, let's move it to Apache git. Also, I don't see a
>> reason to keep it separated from the rest of the source code - it's a part
>> of the project. And it would be easier to track the documentation relevance
>> to the releases if they are together, IMO.
>>
> I think it should be a separate repo, mainly because we probably should not
> allow a 3rd party app have write privilege to our main repo.

We've been through this before. No 3rd-party app (IOW,
untrusted/uncontrolled account) should have write access to *any* ASF
repository. Doesn't matter if you put docs in a separate repo or not;
some bot at readme.io *will not* have write access.

>  On top of
> that, readme.io process has already been tested this way and it works (I
> don't think there is a need to ask them to change it).
>
> If we setup a new repo, do you think Apache GIT would allow an external
> application to connect to it?

See above, not even in your dreams.

The way to do this is for readme.io to provide some way to export the
documentation contents, then we can set up automation *within* the ASF
to update docs in an internal repo.

Even then, there's the question of authorship tracking. Any non-trivial
documentation change requires an ICLA just like code.

-- Brane