Let's keep Apache Ignite docs up-to-date

[Alexey Goncharuk]

Igniters,

Bumping up this discussion.

I have recently found out that we have this process for documenting new
releases [1] which looks quite ridiculous to me.

First, creating a copy of page with next-version suffix is inconvenient and
error-prone: the next-version page is not visible to anyone, moreover, all
suggested edits to current documentation will be lost after the page copy
is created. Second, the documentation changes should be transparent to
users, but now a regular user cannot even review upcoming changes until
they are granted a permission to see/edit hidden pages.

Unless we have very strong reasons to keep documentation on readme.io (by
strong I mean a feature that cannot be implemented using a VCS + doc
generator), I would at least spend some time piloting the 'keep docs in the
VCS' approach.

Thoughts?

[1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document

2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <[hidden email]>:

> I don't like git docs idea, it will require to follow whole
> PR-review-process that requires long time. IMO it is odd work.
> If readme.io provides review process, I suggest to keep it as-is.
>
> чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <[hidden email]>:
>
> > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <[hidden email]>
> > wrote:
> >
> > > +1 for moving docs under Git provided that we find a way to update docs
> > > outside of AI release as it is possible now with readme.io.
> > >
> >
> > I am HUGE +1 for that. The whole problem is that we haven't found a way
> > yet. All I want is to update a page and have it commit to GIT and become
> > available to public right away. Does anyone know any tool that supports
> it?
> >
>

[Sergey Stronchinskiy]

Hi, Igniters

Missed this discussion

+1 for git docs, as far as i can see this approach is used by many projects
and it seems to be quite good.


On 6 March 2018 at 11:44, Alexey Goncharuk <[hidden email]>
wrote:

> Igniters,
>
> Bumping up this discussion.
>
> I have recently found out that we have this process for documenting new
> releases [1] which looks quite ridiculous to me.
>
> First, creating a copy of page with next-version suffix is inconvenient and
> error-prone: the next-version page is not visible to anyone, moreover, all
> suggested edits to current documentation will be lost after the page copy
> is created. Second, the documentation changes should be transparent to
> users, but now a regular user cannot even review upcoming changes until
> they are granted a permission to see/edit hidden pages.
>
> Unless we have very strong reasons to keep documentation on readme.io (by
> strong I mean a feature that cannot be implemented using a VCS + doc
> generator), I would at least spend some time piloting the 'keep docs in the
> VCS' approach.
>
> Thoughts?
>
> [1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document
>
> 2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <[hidden email]>:
>
> > I don't like git docs idea, it will require to follow whole
> > PR-review-process that requires long time. IMO it is odd work.
> > If readme.io provides review process, I suggest to keep it as-is.
> >
> > чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <[hidden email]>:
> >
> > > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <[hidden email]
> >
> > > wrote:
> > >
> > > > +1 for moving docs under Git provided that we find a way to update
> docs
> > > > outside of AI release as it is possible now with readme.io.
> > > >
> > >
> > > I am HUGE +1 for that. The whole problem is that we haven't found a way
> > > yet. All I want is to update a page and have it commit to GIT and
> become
> > > available to public right away. Does anyone know any tool that supports
> > it?
> > >
> >
>

[dmagda]

Guys,

The migration process is in the progress. Here is a discussion where we
exchanged alternate doc engines (let's keep talking there):
http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html

Add to the JIRA ticket as a watcher if you wish to track the progress:
https://issues.apache.org/jira/browse/IGNITE-7595

The goal is to migrate to the new docs by the next Ignite 2.5 release.

--
Denis

On Tue, Mar 6, 2018 at 2:43 AM, Guru Stron <[hidden email]>
wrote:

> Hi, Igniters
>
> Missed this discussion
>
> +1 for git docs, as far as i can see this approach is used by many projects
> and it seems to be quite good.
>
>
> On 6 March 2018 at 11:44, Alexey Goncharuk <[hidden email]>
> wrote:
>
> > Igniters,
> >
> > Bumping up this discussion.
> >
> > I have recently found out that we have this process for documenting new
> > releases [1] which looks quite ridiculous to me.
> >
> > First, creating a copy of page with next-version suffix is inconvenient
> and
> > error-prone: the next-version page is not visible to anyone, moreover,
> all
> > suggested edits to current documentation will be lost after the page copy
> > is created. Second, the documentation changes should be transparent to
> > users, but now a regular user cannot even review upcoming changes until
> > they are granted a permission to see/edit hidden pages.
> >
> > Unless we have very strong reasons to keep documentation on readme.io
> (by
> > strong I mean a feature that cannot be implemented using a VCS + doc
> > generator), I would at least spend some time piloting the 'keep docs in
> the
> > VCS' approach.
> >
> > Thoughts?
> >
> > [1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document
> >
> > 2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <[hidden email]>:
> >
> > > I don't like git docs idea, it will require to follow whole
> > > PR-review-process that requires long time. IMO it is odd work.
> > > If readme.io provides review process, I suggest to keep it as-is.
> > >
> > > чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <[hidden email]>:
> > >
> > > > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <
> [hidden email]
> > >
> > > > wrote:
> > > >
> > > > > +1 for moving docs under Git provided that we find a way to update
> > docs
> > > > > outside of AI release as it is possible now with readme.io.
> > > > >
> > > >
> > > > I am HUGE +1 for that. The whole problem is that we haven't found a
> way
> > > > yet. All I want is to update a page and have it commit to GIT and
> > become
> > > > available to public right away. Does anyone know any tool that
> supports
> > > it?
> > > >
> > >
> >
>