Moving Ignite documentation to github

[Artem Budnikov]

Hello Igniters,

I'd like to return to the discussion about migrating the Ignite
documentation from readme.io to github. The idea emerged long time ago
[1] but hasn't been implemented. I think now is the time to make it happen.

Here are the technical details of the proposed solution:

  * docs are written in asciidoc format and stored in a github repository
  * jekyll is used to generate HTML pages out of the adoc files
  * HTML pages are published on ignite.apache.org in the documentation
    section

This approach is very flexible and allows us to implement any feature
that we need (as opposed to readme.io, which is very limited).

Also, as part of this plan, it makes sense to unite the documentation
for different platforms (java, .NET, c++).

I'm interested in what you have to say about this. Please share your
thoughts.

-Artem

[1]:
http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html

[Nikolay Izhikov-2]

+1.

> 23 июня 2020 г., в 10:02, Artem Budnikov <[hidden email]> написал(а):
>
> Hello Igniters,
>
> I'd like to return to the discussion about migrating the Ignite documentation from readme.io to github. The idea emerged long time ago [1] but hasn't been implemented. I think now is the time to make it happen.
>
> Here are the technical details of the proposed solution:
>
> * docs are written in asciidoc format and stored in a github repository
> * jekyll is used to generate HTML pages out of the adoc files
> * HTML pages are published on ignite.apache.org in the documentation
>   section
>
> This approach is very flexible and allows us to implement any feature that we need (as opposed to readme.io, which is very limited).
>
> Also, as part of this plan, it makes sense to unite the documentation for different platforms (java, .NET, c++).
>
> I'm interested in what you have to say about this. Please share your thoughts.
>
> -Artem
>
> [1]: http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
>

[Alexey Zinoviev]

I'd like this approach, it's easier for contributors to suggest edits.
+1

вт, 23 июн. 2020 г. в 10:03, Nikolay Izhikov <[hidden email]>:

> +1.
>
> > 23 июня 2020 г., в 10:02, Artem Budnikov <[hidden email]>
> написал(а):
> >
> > Hello Igniters,
> >
> > I'd like to return to the discussion about migrating the Ignite
> documentation from readme.io to github. The idea emerged long time ago
> [1] but hasn't been implemented. I think now is the time to make it happen.
> >
> > Here are the technical details of the proposed solution:
> >
> > * docs are written in asciidoc format and stored in a github repository
> > * jekyll is used to generate HTML pages out of the adoc files
> > * HTML pages are published on ignite.apache.org in the documentation
> >   section
> >
> > This approach is very flexible and allows us to implement any feature
> that we need (as opposed to readme.io, which is very limited).
> >
> > Also, as part of this plan, it makes sense to unite the documentation
> for different platforms (java, .NET, c++).
> >
> > I'm interested in what you have to say about this. Please share your
> thoughts.
> >
> > -Artem
> >
> > [1]:
> http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
> >
>
>

[Nikita Amelchev]

+1
For now it's unclear how to add new pages to the site. I hope it'll be
a clear process.

вт, 23 июн. 2020 г. в 10:06, Alexey Zinoviev <[hidden email]>:

>
> I'd like this approach, it's easier for contributors to suggest edits.
> +1
>
> вт, 23 июн. 2020 г. в 10:03, Nikolay Izhikov <[hidden email]>:
>
> > +1.
> >
> > > 23 июня 2020 г., в 10:02, Artem Budnikov <[hidden email]>
> > написал(а):
> > >
> > > Hello Igniters,
> > >
> > > I'd like to return to the discussion about migrating the Ignite
> > documentation from readme.io to github. The idea emerged long time ago
> > [1] but hasn't been implemented. I think now is the time to make it happen.
> > >
> > > Here are the technical details of the proposed solution:
> > >
> > > * docs are written in asciidoc format and stored in a github repository
> > > * jekyll is used to generate HTML pages out of the adoc files
> > > * HTML pages are published on ignite.apache.org in the documentation
> > >   section
> > >
> > > This approach is very flexible and allows us to implement any feature
> > that we need (as opposed to readme.io, which is very limited).
> > >
> > > Also, as part of this plan, it makes sense to unite the documentation
> > for different platforms (java, .NET, c++).
> > >
> > > I'm interested in what you have to say about this. Please share your
> > thoughts.
> > >
> > > -Artem
> > >
> > > [1]:
> > http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
> > >
> >
> >

--
Best wishes,
Amelchev Nikita

[Pavel Tupitsyn]

+1

> stored in a github repository
Do you mean a separate repository here?
I think we should use the main Ignite repo for documentation.



On Tue, Jun 23, 2020 at 10:21 AM Nikita Amelchev <[hidden email]>
wrote:

> +1
> For now it's unclear how to add new pages to the site. I hope it'll be
> a clear process.
>
> вт, 23 июн. 2020 г. в 10:06, Alexey Zinoviev <[hidden email]>:
> >
> > I'd like this approach, it's easier for contributors to suggest edits.
> > +1
> >
> > вт, 23 июн. 2020 г. в 10:03, Nikolay Izhikov <[hidden email]>:
> >
> > > +1.
> > >
> > > > 23 июня 2020 г., в 10:02, Artem Budnikov <
> [hidden email]>
> > > написал(а):
> > > >
> > > > Hello Igniters,
> > > >
> > > > I'd like to return to the discussion about migrating the Ignite
> > > documentation from readme.io to github. The idea emerged long time ago
> > > [1] but hasn't been implemented. I think now is the time to make it
> happen.
> > > >
> > > > Here are the technical details of the proposed solution:
> > > >
> > > > * docs are written in asciidoc format and stored in a github
> repository
> > > > * jekyll is used to generate HTML pages out of the adoc files
> > > > * HTML pages are published on ignite.apache.org in the documentation
> > > >   section
> > > >
> > > > This approach is very flexible and allows us to implement any feature
> > > that we need (as opposed to readme.io, which is very limited).
> > > >
> > > > Also, as part of this plan, it makes sense to unite the documentation
> > > for different platforms (java, .NET, c++).
> > > >
> > > > I'm interested in what you have to say about this. Please share your
> > > thoughts.
> > > >
> > > > -Artem
> > > >
> > > > [1]:
> > >
> http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
> > > >
> > >
> > >
>
>
>
> --
> Best wishes,
> Amelchev Nikita
>

[Ilya Kasnacheev]

Hello!

I'm not really sold on the github version yet, I would like to see a
prototype of such documentation before deciding, so for me it'w
0

Pavel, we don't have enough discipline to make sure that all documentation
is ready at the time of release, and we may need to add notices here and
there after a release is already out. This means, separate git repository,
or at least separate git tag on that repository, is needed.

Regards,
--
Ilya Kasnacheev


вт, 23 июн. 2020 г. в 12:15, Pavel Tupitsyn <[hidden email]>:

> +1
>
> > stored in a github repository
> Do you mean a separate repository here?
> I think we should use the main Ignite repo for documentation.
>
>
>
> On Tue, Jun 23, 2020 at 10:21 AM Nikita Amelchev <[hidden email]>
> wrote:
>
> > +1
> > For now it's unclear how to add new pages to the site. I hope it'll be
> > a clear process.
> >
> > вт, 23 июн. 2020 г. в 10:06, Alexey Zinoviev <[hidden email]>:
> > >
> > > I'd like this approach, it's easier for contributors to suggest edits.
> > > +1
> > >
> > > вт, 23 июн. 2020 г. в 10:03, Nikolay Izhikov <[hidden email]>:
> > >
> > > > +1.
> > > >
> > > > > 23 июня 2020 г., в 10:02, Artem Budnikov <
> > [hidden email]>
> > > > написал(а):
> > > > >
> > > > > Hello Igniters,
> > > > >
> > > > > I'd like to return to the discussion about migrating the Ignite
> > > > documentation from readme.io to github. The idea emerged long time
> ago
> > > > [1] but hasn't been implemented. I think now is the time to make it
> > happen.
> > > > >
> > > > > Here are the technical details of the proposed solution:
> > > > >
> > > > > * docs are written in asciidoc format and stored in a github
> > repository
> > > > > * jekyll is used to generate HTML pages out of the adoc files
> > > > > * HTML pages are published on ignite.apache.org in the
> documentation
> > > > >   section
> > > > >
> > > > > This approach is very flexible and allows us to implement any
> feature
> > > > that we need (as opposed to readme.io, which is very limited).
> > > > >
> > > > > Also, as part of this plan, it makes sense to unite the
> documentation
> > > > for different platforms (java, .NET, c++).
> > > > >
> > > > > I'm interested in what you have to say about this. Please share
> your
> > > > thoughts.
> > > > >
> > > > > -Artem
> > > > >
> > > > > [1]:
> > > >
> >
> http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
> > > > >
> > > >
> > > >
> >
> >
> >
> > --
> > Best wishes,
> > Amelchev Nikita
> >
>

[Artem Budnikov]

Pavel,

Yes, I mean a separate repository. The reason is that documentation is
usually updated after the product version is released. As Ilya pointed
out, keeping the docs in the main Ignite repository would entail
completing the docs before the release date, which is not possible under
current circumstances.

Ilya,

You can look at your company's documentation for a working prototype
turned production-ready approach. The approach has been tested for a
while and proved to be successful, at least with respect to our goals here.

-Artem

On 23.06.2020 12:48, Ilya Kasnacheev wrote:

> Hello!
>
> I'm not really sold on the github version yet, I would like to see a
> prototype of such documentation before deciding, so for me it'w
> 0
>
> Pavel, we don't have enough discipline to make sure that all documentation
> is ready at the time of release, and we may need to add notices here and
> there after a release is already out. This means, separate git repository,
> or at least separate git tag on that repository, is needed.
>
> Regards,

[Pavel Tupitsyn]

Ilya, Artem,

"Separate repo just because we can't finish docs before release"
does not make sense to me. My proposal is:

- Working version is in the master branch
- When a release branch is created, e.g. ignite-2.9, we create
ignite-2.9-docs and update it as long as we want.

Pros (compared to a separate repo):
- Docs can be updated along with the code, same review process
- Visibility - everyone knows about main repo, docs are searchable together
with code in the IDE
- Code snippets can reference the actual code and we make sure they compile
- Code snippets can be tested on TC

GridGain uses a separate repo for their docs, and it proved to be less than
optimal.
Especially when adding samples for new APIs which are not yet released.



On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov <[hidden email]>
wrote:

> Pavel,
>
> Yes, I mean a separate repository. The reason is that documentation is
> usually updated after the product version is released. As Ilya pointed
> out, keeping the docs in the main Ignite repository would entail
> completing the docs before the release date, which is not possible under
> current circumstances.
>
> Ilya,
>
> You can look at your company's documentation for a working prototype
> turned production-ready approach. The approach has been tested for a
> while and proved to be successful, at least with respect to our goals here.
>
> -Artem
>
> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> > Hello!
> >
> > I'm not really sold on the github version yet, I would like to see a
> > prototype of such documentation before deciding, so for me it'w
> > 0
> >
> > Pavel, we don't have enough discipline to make sure that all
> documentation
> > is ready at the time of release, and we may need to add notices here and
> > there after a release is already out. This means, separate git
> repository,
> > or at least separate git tag on that repository, is needed.
> >
> > Regards,
>

[Artem Budnikov]

Pavel,

As far as I can see, all your pros points work just as well for a
separate repository (except for "everybody knows about it"). I don't
mind keeping the docs in Ignite repo as long as I am able to freely
commit to master. Will I be able to do that?

-Artem

On 23.06.2020 14:04, Pavel Tupitsyn wrote:

> Ilya, Artem,
>
> "Separate repo just because we can't finish docs before release"
> does not make sense to me. My proposal is:
>
> - Working version is in the master branch
> - When a release branch is created, e.g. ignite-2.9, we create
> ignite-2.9-docs and update it as long as we want.
>
> Pros (compared to a separate repo):
> - Docs can be updated along with the code, same review process
> - Visibility - everyone knows about main repo, docs are searchable together
> with code in the IDE
> - Code snippets can reference the actual code and we make sure they compile
> - Code snippets can be tested on TC
>
> GridGain uses a separate repo for their docs, and it proved to be less than
> optimal.
> Especially when adding samples for new APIs which are not yet released.
>
>
>
> On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov <[hidden email]>
> wrote:
>
>> Pavel,
>>
>> Yes, I mean a separate repository. The reason is that documentation is
>> usually updated after the product version is released. As Ilya pointed
>> out, keeping the docs in the main Ignite repository would entail
>> completing the docs before the release date, which is not possible under
>> current circumstances.
>>
>> Ilya,
>>
>> You can look at your company's documentation for a working prototype
>> turned production-ready approach. The approach has been tested for a
>> while and proved to be successful, at least with respect to our goals here.
>>
>> -Artem
>>
>> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>> Hello!
>>>
>>> I'm not really sold on the github version yet, I would like to see a
>>> prototype of such documentation before deciding, so for me it'w
>>> 0
>>>
>>> Pavel, we don't have enough discipline to make sure that all
>> documentation
>>> is ready at the time of release, and we may need to add notices here and
>>> there after a release is already out. This means, separate git
>> repository,
>>> or at least separate git tag on that repository, is needed.
>>>
>>> Regards,

[Artem Budnikov]

Pavel,

> I don't think so: we can't add snippets pointing to new APIs from a
> separate repo,
Snippets are kept together with the docs, they /don't need/ to be stored
in the main repo, although they can. They are compilable and up to date.
I update the docs and API samples for features that hasn't been released
in the GridGain docs and never thought it was a problem. I understand
that you don't want to do extra work when adding code samples, but it
looks like just an inconvenience. Let me suggest this: Let's think about
a solution that will be comfortable for you, I'm pretty sure this
inconvenience can be solved technically. But I need time to think it
through.

> we can't see the docs when doing global search (and/or replace) from
> the IDE.
I think you can add the docs repo to your IDE as a project. I used to do
it in the beginning but then switched to Sublime Text, because it's more
convenient to me. We are looking at it from different perspectives. I'm
trying to create a process that is comfortable for tech writers rather
than developers. And everybody has to accept some kind of a compromise:)

>> Well, no one is able to "freely" commit code to Apache master, there
>> is a process to follow - CI, reviews, etc.
>> Same should happen for the docs, separate repo or not.
>> But a separate repo will require separate ownership/management
>> (probably?),
>> but we already have everything in the main repo, why introduce overhead?
Just think about it from my perspective. That creates a HUUUGE overhead
for technical writers who work on the docs, and they are the ones who
provide 90% of updates. I agree about the review process, and I'm going
to think it over. But now it seems that we don't have to impose any
strict process that impedes preparation of the docs.

-Artem


On 23.06.2020 15:35, Pavel Tupitsyn wrote:

> > all your pros points work just as well for a separate repository
> I don't think so: we can't add snippets pointing to new APIs from a
> separate repo,
> we can't see the docs when doing global search (and/or replace) from
> the IDE.
>
> > I am able to freely commit to master
> Well, no one is able to "freely" commit code to Apache master, there
> is a process to follow - CI, reviews, etc.
> Same should happen for the docs, separate repo or not.
> But a separate repo will require separate ownership/management
> (probably?),
> but we already have everything in the main repo, why introduce overhead?
>
> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     Pavel,
>
>     As far as I can see, all your pros points work just as well for a
>     separate repository (except for "everybody knows about it"). I don't
>     mind keeping the docs in Ignite repo as long as I am able to freely
>     commit to master. Will I be able to do that?
>
>     -Artem
>
>     On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>     > Ilya, Artem,
>     >
>     > "Separate repo just because we can't finish docs before release"
>     > does not make sense to me. My proposal is:
>     >
>     > - Working version is in the master branch
>     > - When a release branch is created, e.g. ignite-2.9, we create
>     > ignite-2.9-docs and update it as long as we want.
>     >
>     > Pros (compared to a separate repo):
>     > - Docs can be updated along with the code, same review process
>     > - Visibility - everyone knows about main repo, docs are
>     searchable together
>     > with code in the IDE
>     > - Code snippets can reference the actual code and we make sure
>     they compile
>     > - Code snippets can be tested on TC
>     >
>     > GridGain uses a separate repo for their docs, and it proved to
>     be less than
>     > optimal.
>     > Especially when adding samples for new APIs which are not yet
>     released.
>     >
>     >
>     >
>     > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>     <[hidden email] <mailto:[hidden email]>>
>     > wrote:
>     >
>     >> Pavel,
>     >>
>     >> Yes, I mean a separate repository. The reason is that
>     documentation is
>     >> usually updated after the product version is released. As Ilya
>     pointed
>     >> out, keeping the docs in the main Ignite repository would entail
>     >> completing the docs before the release date, which is not
>     possible under
>     >> current circumstances.
>     >>
>     >> Ilya,
>     >>
>     >> You can look at your company's documentation for a working
>     prototype
>     >> turned production-ready approach. The approach has been tested
>     for a
>     >> while and proved to be successful, at least with respect to our
>     goals here.
>     >>
>     >> -Artem
>     >>
>     >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>     >>> Hello!
>     >>>
>     >>> I'm not really sold on the github version yet, I would like to
>     see a
>     >>> prototype of such documentation before deciding, so for me it'w
>     >>> 0
>     >>>
>     >>> Pavel, we don't have enough discipline to make sure that all
>     >> documentation
>     >>> is ready at the time of release, and we may need to add
>     notices here and
>     >>> there after a release is already out. This means, separate git
>     >> repository,
>     >>> or at least separate git tag on that repository, is needed.
>     >>>
>     >>> Regards,
>

[Nikolay Izhikov-2]

+1 to keep docs and sources together.
-1 to keep docs in external repository.

> 23 июня 2020 г., в 16:47, Artem Budnikov <[hidden email]> написал(а):
>
> Pavel,
>
>> I don't think so: we can't add snippets pointing to new APIs from a separate repo,
> Snippets are kept together with the docs, they /don't need/ to be stored in the main repo, although they can. They are compilable and up to date. I update the docs and API samples for features that hasn't been released in the GridGain docs and never thought it was a problem. I understand that you don't want to do extra work when adding code samples, but it looks like just an inconvenience. Let me suggest this: Let's think about a solution that will be comfortable for you, I'm pretty sure this inconvenience can be solved technically. But I need time to think it through.
>
>> we can't see the docs when doing global search (and/or replace) from the IDE.
> I think you can add the docs repo to your IDE as a project. I used to do it in the beginning but then switched to Sublime Text, because it's more convenient to me. We are looking at it from different perspectives. I'm trying to create a process that is comfortable for tech writers rather than developers. And everybody has to accept some kind of a compromise:)
>
>>> Well, no one is able to "freely" commit code to Apache master, there is a process to follow - CI, reviews, etc.
>>> Same should happen for the docs, separate repo or not.
>>> But a separate repo will require separate ownership/management (probably?),
>>> but we already have everything in the main repo, why introduce overhead?
> Just think about it from my perspective. That creates a HUUUGE overhead for technical writers who work on the docs, and they are the ones who provide 90% of updates. I agree about the review process, and I'm going to think it over. But now it seems that we don't have to impose any strict process that impedes preparation of the docs.
>
> -Artem
>
>
> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
>> > all your pros points work just as well for a separate repository
>> I don't think so: we can't add snippets pointing to new APIs from a separate repo,
>> we can't see the docs when doing global search (and/or replace) from the IDE.
>>
>> > I am able to freely commit to master
>> Well, no one is able to "freely" commit code to Apache master, there is a process to follow - CI, reviews, etc.
>> Same should happen for the docs, separate repo or not.
>> But a separate repo will require separate ownership/management (probably?),
>> but we already have everything in the main repo, why introduce overhead?
>>
>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov <[hidden email] <mailto:[hidden email]>> wrote:
>>
>>    Pavel,
>>
>>    As far as I can see, all your pros points work just as well for a
>>    separate repository (except for "everybody knows about it"). I don't
>>    mind keeping the docs in Ignite repo as long as I am able to freely
>>    commit to master. Will I be able to do that?
>>
>>    -Artem
>>
>>    On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>>    > Ilya, Artem,
>>    >
>>    > "Separate repo just because we can't finish docs before release"
>>    > does not make sense to me. My proposal is:
>>    >
>>    > - Working version is in the master branch
>>    > - When a release branch is created, e.g. ignite-2.9, we create
>>    > ignite-2.9-docs and update it as long as we want.
>>    >
>>    > Pros (compared to a separate repo):
>>    > - Docs can be updated along with the code, same review process
>>    > - Visibility - everyone knows about main repo, docs are
>>    searchable together
>>    > with code in the IDE
>>    > - Code snippets can reference the actual code and we make sure
>>    they compile
>>    > - Code snippets can be tested on TC
>>    >
>>    > GridGain uses a separate repo for their docs, and it proved to
>>    be less than
>>    > optimal.
>>    > Especially when adding samples for new APIs which are not yet
>>    released.
>>    >
>>    >
>>    >
>>    > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>>    <[hidden email] <mailto:[hidden email]>>
>>    > wrote:
>>    >
>>    >> Pavel,
>>    >>
>>    >> Yes, I mean a separate repository. The reason is that
>>    documentation is
>>    >> usually updated after the product version is released. As Ilya
>>    pointed
>>    >> out, keeping the docs in the main Ignite repository would entail
>>    >> completing the docs before the release date, which is not
>>    possible under
>>    >> current circumstances.
>>    >>
>>    >> Ilya,
>>    >>
>>    >> You can look at your company's documentation for a working
>>    prototype
>>    >> turned production-ready approach. The approach has been tested
>>    for a
>>    >> while and proved to be successful, at least with respect to our
>>    goals here.
>>    >>
>>    >> -Artem
>>    >>
>>    >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>    >>> Hello!
>>    >>>
>>    >>> I'm not really sold on the github version yet, I would like to
>>    see a
>>    >>> prototype of such documentation before deciding, so for me it'w
>>    >>> 0
>>    >>>
>>    >>> Pavel, we don't have enough discipline to make sure that all
>>    >> documentation
>>    >>> is ready at the time of release, and we may need to add
>>    notices here and
>>    >>> there after a release is already out. This means, separate git
>>    >> repository,
>>    >>> or at least separate git tag on that repository, is needed.
>>    >>>
>>    >>> Regards,
>>

[dmagda]

I believe that by keeping the documentation sources in the same repository
with the source code will help us to prepare and release all the release
artifacts at the same time. So, +1 for hosting raw documentation ascii-doc
pages in the main Ignite repo. However, the HTML version needs to reside on
the Ignite website, which is similar to the API docs. We can create tools
to do this in one click.

Post-reviews are not prohibited in Apache, quite the opposite, and they
suit the documentation contribution process better. It's ok if committers
to the documentation merge the changes first and ask for a review later if
needed.

-
Denis


On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <[hidden email]>
wrote:

> Pavel,
>
> > I don't think so: we can't add snippets pointing to new APIs from a
> > separate repo,
> Snippets are kept together with the docs, they /don't need/ to be stored
> in the main repo, although they can. They are compilable and up to date.
> I update the docs and API samples for features that hasn't been released
> in the GridGain docs and never thought it was a problem. I understand
> that you don't want to do extra work when adding code samples, but it
> looks like just an inconvenience. Let me suggest this: Let's think about
> a solution that will be comfortable for you, I'm pretty sure this
> inconvenience can be solved technically. But I need time to think it
> through.
>
> > we can't see the docs when doing global search (and/or replace) from
> > the IDE.
> I think you can add the docs repo to your IDE as a project. I used to do
> it in the beginning but then switched to Sublime Text, because it's more
> convenient to me. We are looking at it from different perspectives. I'm
> trying to create a process that is comfortable for tech writers rather
> than developers. And everybody has to accept some kind of a compromise:)
>
> >> Well, no one is able to "freely" commit code to Apache master, there
> >> is a process to follow - CI, reviews, etc.
> >> Same should happen for the docs, separate repo or not.
> >> But a separate repo will require separate ownership/management
> >> (probably?),
> >> but we already have everything in the main repo, why introduce overhead?
> Just think about it from my perspective. That creates a HUUUGE overhead
> for technical writers who work on the docs, and they are the ones who
> provide 90% of updates. I agree about the review process, and I'm going
> to think it over. But now it seems that we don't have to impose any
> strict process that impedes preparation of the docs.
>
> -Artem
>
>
> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
> > > all your pros points work just as well for a separate repository
> > I don't think so: we can't add snippets pointing to new APIs from a
> > separate repo,
> > we can't see the docs when doing global search (and/or replace) from
> > the IDE.
> >
> > > I am able to freely commit to master
> > Well, no one is able to "freely" commit code to Apache master, there
> > is a process to follow - CI, reviews, etc.
> > Same should happen for the docs, separate repo or not.
> > But a separate repo will require separate ownership/management
> > (probably?),
> > but we already have everything in the main repo, why introduce overhead?
> >
> > On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> > <[hidden email] <mailto:[hidden email]>>
> wrote:
> >
> >     Pavel,
> >
> >     As far as I can see, all your pros points work just as well for a
> >     separate repository (except for "everybody knows about it"). I don't
> >     mind keeping the docs in Ignite repo as long as I am able to freely
> >     commit to master. Will I be able to do that?
> >
> >     -Artem
> >
> >     On 23.06.2020 14:04, Pavel Tupitsyn wrote:
> >     > Ilya, Artem,
> >     >
> >     > "Separate repo just because we can't finish docs before release"
> >     > does not make sense to me. My proposal is:
> >     >
> >     > - Working version is in the master branch
> >     > - When a release branch is created, e.g. ignite-2.9, we create
> >     > ignite-2.9-docs and update it as long as we want.
> >     >
> >     > Pros (compared to a separate repo):
> >     > - Docs can be updated along with the code, same review process
> >     > - Visibility - everyone knows about main repo, docs are
> >     searchable together
> >     > with code in the IDE
> >     > - Code snippets can reference the actual code and we make sure
> >     they compile
> >     > - Code snippets can be tested on TC
> >     >
> >     > GridGain uses a separate repo for their docs, and it proved to
> >     be less than
> >     > optimal.
> >     > Especially when adding samples for new APIs which are not yet
> >     released.
> >     >
> >     >
> >     >
> >     > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
> >     <[hidden email] <mailto:[hidden email]>>
> >     > wrote:
> >     >
> >     >> Pavel,
> >     >>
> >     >> Yes, I mean a separate repository. The reason is that
> >     documentation is
> >     >> usually updated after the product version is released. As Ilya
> >     pointed
> >     >> out, keeping the docs in the main Ignite repository would entail
> >     >> completing the docs before the release date, which is not
> >     possible under
> >     >> current circumstances.
> >     >>
> >     >> Ilya,
> >     >>
> >     >> You can look at your company's documentation for a working
> >     prototype
> >     >> turned production-ready approach. The approach has been tested
> >     for a
> >     >> while and proved to be successful, at least with respect to our
> >     goals here.
> >     >>
> >     >> -Artem
> >     >>
> >     >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> >     >>> Hello!
> >     >>>
> >     >>> I'm not really sold on the github version yet, I would like to
> >     see a
> >     >>> prototype of such documentation before deciding, so for me it'w
> >     >>> 0
> >     >>>
> >     >>> Pavel, we don't have enough discipline to make sure that all
> >     >> documentation
> >     >>> is ready at the time of release, and we may need to add
> >     notices here and
> >     >>> there after a release is already out. This means, separate git
> >     >> repository,
> >     >>> or at least separate git tag on that repository, is needed.
> >     >>>
> >     >>> Regards,
> >
>

[Artem Budnikov]

OK, let's give it a try.

The way I see it, the documentation source files will be located in the
"/docs" folder, including UI templates/styles, asciidoc files, and build
scripts. I'll start experimenting with this and will let you know when
basic setup is ready.

-Artem

On 23.06.2020 20:19, Denis Magda wrote:

> I believe that by keeping the documentation sources in the same repository
> with the source code will help us to prepare and release all the release
> artifacts at the same time. So, +1 for hosting raw documentation ascii-doc
> pages in the main Ignite repo. However, the HTML version needs to reside on
> the Ignite website, which is similar to the API docs. We can create tools
> to do this in one click.
>
> Post-reviews are not prohibited in Apache, quite the opposite, and they
> suit the documentation contribution process better. It's ok if committers
> to the documentation merge the changes first and ask for a review later if
> needed.
>
> -
> Denis
>
>
> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <[hidden email]>
> wrote:
>
>> Pavel,
>>
>>> I don't think so: we can't add snippets pointing to new APIs from a
>>> separate repo,
>> Snippets are kept together with the docs, they /don't need/ to be stored
>> in the main repo, although they can. They are compilable and up to date.
>> I update the docs and API samples for features that hasn't been released
>> in the GridGain docs and never thought it was a problem. I understand
>> that you don't want to do extra work when adding code samples, but it
>> looks like just an inconvenience. Let me suggest this: Let's think about
>> a solution that will be comfortable for you, I'm pretty sure this
>> inconvenience can be solved technically. But I need time to think it
>> through.
>>
>>> we can't see the docs when doing global search (and/or replace) from
>>> the IDE.
>> I think you can add the docs repo to your IDE as a project. I used to do
>> it in the beginning but then switched to Sublime Text, because it's more
>> convenient to me. We are looking at it from different perspectives. I'm
>> trying to create a process that is comfortable for tech writers rather
>> than developers. And everybody has to accept some kind of a compromise:)
>>
>>>> Well, no one is able to "freely" commit code to Apache master, there
>>>> is a process to follow - CI, reviews, etc.
>>>> Same should happen for the docs, separate repo or not.
>>>> But a separate repo will require separate ownership/management
>>>> (probably?),
>>>> but we already have everything in the main repo, why introduce overhead?
>> Just think about it from my perspective. That creates a HUUUGE overhead
>> for technical writers who work on the docs, and they are the ones who
>> provide 90% of updates. I agree about the review process, and I'm going
>> to think it over. But now it seems that we don't have to impose any
>> strict process that impedes preparation of the docs.
>>
>> -Artem
>>
>>
>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
>>>> all your pros points work just as well for a separate repository
>>> I don't think so: we can't add snippets pointing to new APIs from a
>>> separate repo,
>>> we can't see the docs when doing global search (and/or replace) from
>>> the IDE.
>>>
>>>> I am able to freely commit to master
>>> Well, no one is able to "freely" commit code to Apache master, there
>>> is a process to follow - CI, reviews, etc.
>>> Same should happen for the docs, separate repo or not.
>>> But a separate repo will require separate ownership/management
>>> (probably?),
>>> but we already have everything in the main repo, why introduce overhead?
>>>
>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
>>> <[hidden email] <mailto:[hidden email]>>
>> wrote:
>>>      Pavel,
>>>
>>>      As far as I can see, all your pros points work just as well for a
>>>      separate repository (except for "everybody knows about it"). I don't
>>>      mind keeping the docs in Ignite repo as long as I am able to freely
>>>      commit to master. Will I be able to do that?
>>>
>>>      -Artem
>>>
>>>      On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>>>      > Ilya, Artem,
>>>      >
>>>      > "Separate repo just because we can't finish docs before release"
>>>      > does not make sense to me. My proposal is:
>>>      >
>>>      > - Working version is in the master branch
>>>      > - When a release branch is created, e.g. ignite-2.9, we create
>>>      > ignite-2.9-docs and update it as long as we want.
>>>      >
>>>      > Pros (compared to a separate repo):
>>>      > - Docs can be updated along with the code, same review process
>>>      > - Visibility - everyone knows about main repo, docs are
>>>      searchable together
>>>      > with code in the IDE
>>>      > - Code snippets can reference the actual code and we make sure
>>>      they compile
>>>      > - Code snippets can be tested on TC
>>>      >
>>>      > GridGain uses a separate repo for their docs, and it proved to
>>>      be less than
>>>      > optimal.
>>>      > Especially when adding samples for new APIs which are not yet
>>>      released.
>>>      >
>>>      >
>>>      >
>>>      > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>>>      <[hidden email] <mailto:[hidden email]>>
>>>      > wrote:
>>>      >
>>>      >> Pavel,
>>>      >>
>>>      >> Yes, I mean a separate repository. The reason is that
>>>      documentation is
>>>      >> usually updated after the product version is released. As Ilya
>>>      pointed
>>>      >> out, keeping the docs in the main Ignite repository would entail
>>>      >> completing the docs before the release date, which is not
>>>      possible under
>>>      >> current circumstances.
>>>      >>
>>>      >> Ilya,
>>>      >>
>>>      >> You can look at your company's documentation for a working
>>>      prototype
>>>      >> turned production-ready approach. The approach has been tested
>>>      for a
>>>      >> while and proved to be successful, at least with respect to our
>>>      goals here.
>>>      >>
>>>      >> -Artem
>>>      >>
>>>      >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>>      >>> Hello!
>>>      >>>
>>>      >>> I'm not really sold on the github version yet, I would like to
>>>      see a
>>>      >>> prototype of such documentation before deciding, so for me it'w
>>>      >>> 0
>>>      >>>
>>>      >>> Pavel, we don't have enough discipline to make sure that all
>>>      >> documentation
>>>      >>> is ready at the time of release, and we may need to add
>>>      notices here and
>>>      >>> there after a release is already out. This means, separate git
>>>      >> repository,
>>>      >>> or at least separate git tag on that repository, is needed.
>>>      >>>
>>>      >>> Regards,
>>>

[Sergey Stronchinskiy]

+1 for migrating docs to github. It will allow an easier contribution for
docs, I think. As a nice feature - adding an edit link (submit PR for docs)
to the document page on site.

As for keeping them separate - Microsoft keeps docs for it's products in
separate repos, for example.

On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <[hidden email]>
wrote:

> OK, let's give it a try.
>
> The way I see it, the documentation source files will be located in the
> "/docs" folder, including UI templates/styles, asciidoc files, and build
> scripts. I'll start experimenting with this and will let you know when
> basic setup is ready.
>
> -Artem
>
> On 23.06.2020 20:19, Denis Magda wrote:
> > I believe that by keeping the documentation sources in the same
> repository
> > with the source code will help us to prepare and release all the release
> > artifacts at the same time. So, +1 for hosting raw documentation
> ascii-doc
> > pages in the main Ignite repo. However, the HTML version needs to reside
> on
> > the Ignite website, which is similar to the API docs. We can create tools
> > to do this in one click.
> >
> > Post-reviews are not prohibited in Apache, quite the opposite, and they
> > suit the documentation contribution process better. It's ok if committers
> > to the documentation merge the changes first and ask for a review later
> if
> > needed.
> >
> > -
> > Denis
> >
> >
> > On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
> [hidden email]>
> > wrote:
> >
> >> Pavel,
> >>
> >>> I don't think so: we can't add snippets pointing to new APIs from a
> >>> separate repo,
> >> Snippets are kept together with the docs, they /don't need/ to be stored
> >> in the main repo, although they can. They are compilable and up to date.
> >> I update the docs and API samples for features that hasn't been released
> >> in the GridGain docs and never thought it was a problem. I understand
> >> that you don't want to do extra work when adding code samples, but it
> >> looks like just an inconvenience. Let me suggest this: Let's think about
> >> a solution that will be comfortable for you, I'm pretty sure this
> >> inconvenience can be solved technically. But I need time to think it
> >> through.
> >>
> >>> we can't see the docs when doing global search (and/or replace) from
> >>> the IDE.
> >> I think you can add the docs repo to your IDE as a project. I used to do
> >> it in the beginning but then switched to Sublime Text, because it's more
> >> convenient to me. We are looking at it from different perspectives. I'm
> >> trying to create a process that is comfortable for tech writers rather
> >> than developers. And everybody has to accept some kind of a compromise:)
> >>
> >>>> Well, no one is able to "freely" commit code to Apache master, there
> >>>> is a process to follow - CI, reviews, etc.
> >>>> Same should happen for the docs, separate repo or not.
> >>>> But a separate repo will require separate ownership/management
> >>>> (probably?),
> >>>> but we already have everything in the main repo, why introduce
> overhead?
> >> Just think about it from my perspective. That creates a HUUUGE overhead
> >> for technical writers who work on the docs, and they are the ones who
> >> provide 90% of updates. I agree about the review process, and I'm going
> >> to think it over. But now it seems that we don't have to impose any
> >> strict process that impedes preparation of the docs.
> >>
> >> -Artem
> >>
> >>
> >> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
> >>>> all your pros points work just as well for a separate repository
> >>> I don't think so: we can't add snippets pointing to new APIs from a
> >>> separate repo,
> >>> we can't see the docs when doing global search (and/or replace) from
> >>> the IDE.
> >>>
> >>>> I am able to freely commit to master
> >>> Well, no one is able to "freely" commit code to Apache master, there
> >>> is a process to follow - CI, reviews, etc.
> >>> Same should happen for the docs, separate repo or not.
> >>> But a separate repo will require separate ownership/management
> >>> (probably?),
> >>> but we already have everything in the main repo, why introduce
> overhead?
> >>>
> >>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> >>> <[hidden email] <mailto:[hidden email]>>
> >> wrote:
> >>>      Pavel,
> >>>
> >>>      As far as I can see, all your pros points work just as well for a
> >>>      separate repository (except for "everybody knows about it"). I
> don't
> >>>      mind keeping the docs in Ignite repo as long as I am able to
> freely
> >>>      commit to master. Will I be able to do that?
> >>>
> >>>      -Artem
> >>>
> >>>      On 23.06.2020 14:04, Pavel Tupitsyn wrote:
> >>>      > Ilya, Artem,
> >>>      >
> >>>      > "Separate repo just because we can't finish docs before release"
> >>>      > does not make sense to me. My proposal is:
> >>>      >
> >>>      > - Working version is in the master branch
> >>>      > - When a release branch is created, e.g. ignite-2.9, we create
> >>>      > ignite-2.9-docs and update it as long as we want.
> >>>      >
> >>>      > Pros (compared to a separate repo):
> >>>      > - Docs can be updated along with the code, same review process
> >>>      > - Visibility - everyone knows about main repo, docs are
> >>>      searchable together
> >>>      > with code in the IDE
> >>>      > - Code snippets can reference the actual code and we make sure
> >>>      they compile
> >>>      > - Code snippets can be tested on TC
> >>>      >
> >>>      > GridGain uses a separate repo for their docs, and it proved to
> >>>      be less than
> >>>      > optimal.
> >>>      > Especially when adding samples for new APIs which are not yet
> >>>      released.
> >>>      >
> >>>      >
> >>>      >
> >>>      > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
> >>>      <[hidden email] <mailto:[hidden email]
> >>
> >>>      > wrote:
> >>>      >
> >>>      >> Pavel,
> >>>      >>
> >>>      >> Yes, I mean a separate repository. The reason is that
> >>>      documentation is
> >>>      >> usually updated after the product version is released. As Ilya
> >>>      pointed
> >>>      >> out, keeping the docs in the main Ignite repository would
> entail
> >>>      >> completing the docs before the release date, which is not
> >>>      possible under
> >>>      >> current circumstances.
> >>>      >>
> >>>      >> Ilya,
> >>>      >>
> >>>      >> You can look at your company's documentation for a working
> >>>      prototype
> >>>      >> turned production-ready approach. The approach has been tested
> >>>      for a
> >>>      >> while and proved to be successful, at least with respect to our
> >>>      goals here.
> >>>      >>
> >>>      >> -Artem
> >>>      >>
> >>>      >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> >>>      >>> Hello!
> >>>      >>>
> >>>      >>> I'm not really sold on the github version yet, I would like to
> >>>      see a
> >>>      >>> prototype of such documentation before deciding, so for me
> it'w
> >>>      >>> 0
> >>>      >>>
> >>>      >>> Pavel, we don't have enough discipline to make sure that all
> >>>      >> documentation
> >>>      >>> is ready at the time of release, and we may need to add
> >>>      notices here and
> >>>      >>> there after a release is already out. This means, separate git
> >>>      >> repository,
> >>>      >>> or at least separate git tag on that repository, is needed.
> >>>      >>>
> >>>      >>> Regards,
> >>>
>

[Artem Budnikov]

Hi everyone,

I've prepared the initial set of source files for the Ignite
documentation. If you are interested, you can take a look at
https://github.com/apache/ignite/tree/IGNITE-7595/docs

You can run a local web-server (jekyll) if you want to view the docs in
your browser. Refer to the README.adoc for instructions. Some people had
troubles installing Jekyll locally, so I added an instruction on how to
use jekyll docker image.

If you have any comments on the overall approach, please let me know.
The styles and content are still a work in progress, so please don't
report issues related to that.

-Artem

On 26.06.2020 01:54, Guru Stron wrote:

> +1 for migrating docs to github. It will allow an easier contribution for
> docs, I think. As a nice feature - adding an edit link (submit PR for docs)
> to the document page on site.
>
> As for keeping them separate - Microsoft keeps docs for it's products in
> separate repos, for example.
>
> On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <[hidden email]>
> wrote:
>
>> OK, let's give it a try.
>>
>> The way I see it, the documentation source files will be located in the
>> "/docs" folder, including UI templates/styles, asciidoc files, and build
>> scripts. I'll start experimenting with this and will let you know when
>> basic setup is ready.
>>
>> -Artem
>>
>> On 23.06.2020 20:19, Denis Magda wrote:
>>> I believe that by keeping the documentation sources in the same
>> repository
>>> with the source code will help us to prepare and release all the release
>>> artifacts at the same time. So, +1 for hosting raw documentation
>> ascii-doc
>>> pages in the main Ignite repo. However, the HTML version needs to reside
>> on
>>> the Ignite website, which is similar to the API docs. We can create tools
>>> to do this in one click.
>>>
>>> Post-reviews are not prohibited in Apache, quite the opposite, and they
>>> suit the documentation contribution process better. It's ok if committers
>>> to the documentation merge the changes first and ask for a review later
>> if
>>> needed.
>>>
>>> -
>>> Denis
>>>
>>>
>>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
>> [hidden email]>
>>> wrote:
>>>
>>>> Pavel,
>>>>
>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>> separate repo,
>>>> Snippets are kept together with the docs, they /don't need/ to be stored
>>>> in the main repo, although they can. They are compilable and up to date.
>>>> I update the docs and API samples for features that hasn't been released
>>>> in the GridGain docs and never thought it was a problem. I understand
>>>> that you don't want to do extra work when adding code samples, but it
>>>> looks like just an inconvenience. Let me suggest this: Let's think about
>>>> a solution that will be comfortable for you, I'm pretty sure this
>>>> inconvenience can be solved technically. But I need time to think it
>>>> through.
>>>>
>>>>> we can't see the docs when doing global search (and/or replace) from
>>>>> the IDE.
>>>> I think you can add the docs repo to your IDE as a project. I used to do
>>>> it in the beginning but then switched to Sublime Text, because it's more
>>>> convenient to me. We are looking at it from different perspectives. I'm
>>>> trying to create a process that is comfortable for tech writers rather
>>>> than developers. And everybody has to accept some kind of a compromise:)
>>>>
>>>>>> Well, no one is able to "freely" commit code to Apache master, there
>>>>>> is a process to follow - CI, reviews, etc.
>>>>>> Same should happen for the docs, separate repo or not.
>>>>>> But a separate repo will require separate ownership/management
>>>>>> (probably?),
>>>>>> but we already have everything in the main repo, why introduce
>> overhead?
>>>> Just think about it from my perspective. That creates a HUUUGE overhead
>>>> for technical writers who work on the docs, and they are the ones who
>>>> provide 90% of updates. I agree about the review process, and I'm going
>>>> to think it over. But now it seems that we don't have to impose any
>>>> strict process that impedes preparation of the docs.
>>>>
>>>> -Artem
>>>>
>>>>
>>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
>>>>>> all your pros points work just as well for a separate repository
>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>> separate repo,
>>>>> we can't see the docs when doing global search (and/or replace) from
>>>>> the IDE.
>>>>>
>>>>>> I am able to freely commit to master
>>>>> Well, no one is able to "freely" commit code to Apache master, there
>>>>> is a process to follow - CI, reviews, etc.
>>>>> Same should happen for the docs, separate repo or not.
>>>>> But a separate repo will require separate ownership/management
>>>>> (probably?),
>>>>> but we already have everything in the main repo, why introduce
>> overhead?
>>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
>>>>> <[hidden email] <mailto:[hidden email]>>
>>>> wrote:
>>>>>       Pavel,
>>>>>
>>>>>       As far as I can see, all your pros points work just as well for a
>>>>>       separate repository (except for "everybody knows about it"). I
>> don't
>>>>>       mind keeping the docs in Ignite repo as long as I am able to
>> freely
>>>>>       commit to master. Will I be able to do that?
>>>>>
>>>>>       -Artem
>>>>>
>>>>>       On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>>>>>       > Ilya, Artem,
>>>>>       >
>>>>>       > "Separate repo just because we can't finish docs before release"
>>>>>       > does not make sense to me. My proposal is:
>>>>>       >
>>>>>       > - Working version is in the master branch
>>>>>       > - When a release branch is created, e.g. ignite-2.9, we create
>>>>>       > ignite-2.9-docs and update it as long as we want.
>>>>>       >
>>>>>       > Pros (compared to a separate repo):
>>>>>       > - Docs can be updated along with the code, same review process
>>>>>       > - Visibility - everyone knows about main repo, docs are
>>>>>       searchable together
>>>>>       > with code in the IDE
>>>>>       > - Code snippets can reference the actual code and we make sure
>>>>>       they compile
>>>>>       > - Code snippets can be tested on TC
>>>>>       >
>>>>>       > GridGain uses a separate repo for their docs, and it proved to
>>>>>       be less than
>>>>>       > optimal.
>>>>>       > Especially when adding samples for new APIs which are not yet
>>>>>       released.
>>>>>       >
>>>>>       >
>>>>>       >
>>>>>       > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>>>>>       <[hidden email] <mailto:[hidden email]
>>>>>       > wrote:
>>>>>       >
>>>>>       >> Pavel,
>>>>>       >>
>>>>>       >> Yes, I mean a separate repository. The reason is that
>>>>>       documentation is
>>>>>       >> usually updated after the product version is released. As Ilya
>>>>>       pointed
>>>>>       >> out, keeping the docs in the main Ignite repository would
>> entail
>>>>>       >> completing the docs before the release date, which is not
>>>>>       possible under
>>>>>       >> current circumstances.
>>>>>       >>
>>>>>       >> Ilya,
>>>>>       >>
>>>>>       >> You can look at your company's documentation for a working
>>>>>       prototype
>>>>>       >> turned production-ready approach. The approach has been tested
>>>>>       for a
>>>>>       >> while and proved to be successful, at least with respect to our
>>>>>       goals here.
>>>>>       >>
>>>>>       >> -Artem
>>>>>       >>
>>>>>       >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>>>>       >>> Hello!
>>>>>       >>>
>>>>>       >>> I'm not really sold on the github version yet, I would like to
>>>>>       see a
>>>>>       >>> prototype of such documentation before deciding, so for me
>> it'w
>>>>>       >>> 0
>>>>>       >>>
>>>>>       >>> Pavel, we don't have enough discipline to make sure that all
>>>>>       >> documentation
>>>>>       >>> is ready at the time of release, and we may need to add
>>>>>       notices here and
>>>>>       >>> there after a release is already out. This means, separate git
>>>>>       >> repository,
>>>>>       >>> or at least separate git tag on that repository, is needed.
>>>>>       >>>
>>>>>       >>> Regards,
>>>>>

[Ilya Kasnacheev]

Hello!

I was able to eventually run it. The trick is to only install bundler with
apt, and not jekyll, once you install any other gems, they collide and it
will fail.

Looks OK. For some reason "Working with SQL" leads nowhere.

Regards,
--
Ilya Kasnacheev


пт, 17 июл. 2020 г. в 15:27, Artem Budnikov <[hidden email]>:

> Hi everyone,
>
> I've prepared the initial set of source files for the Ignite
> documentation. If you are interested, you can take a look at
> https://github.com/apache/ignite/tree/IGNITE-7595/docs
>
> You can run a local web-server (jekyll) if you want to view the docs in
> your browser. Refer to the README.adoc for instructions. Some people had
> troubles installing Jekyll locally, so I added an instruction on how to
> use jekyll docker image.
>
> If you have any comments on the overall approach, please let me know.
> The styles and content are still a work in progress, so please don't
> report issues related to that.
>
> -Artem
>
> On 26.06.2020 01:54, Guru Stron wrote:
> > +1 for migrating docs to github. It will allow an easier contribution for
> > docs, I think. As a nice feature - adding an edit link (submit PR for
> docs)
> > to the document page on site.
> >
> > As for keeping them separate - Microsoft keeps docs for it's products in
> > separate repos, for example.
> >
> > On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <
> [hidden email]>
> > wrote:
> >
> >> OK, let's give it a try.
> >>
> >> The way I see it, the documentation source files will be located in the
> >> "/docs" folder, including UI templates/styles, asciidoc files, and build
> >> scripts. I'll start experimenting with this and will let you know when
> >> basic setup is ready.
> >>
> >> -Artem
> >>
> >> On 23.06.2020 20:19, Denis Magda wrote:
> >>> I believe that by keeping the documentation sources in the same
> >> repository
> >>> with the source code will help us to prepare and release all the
> release
> >>> artifacts at the same time. So, +1 for hosting raw documentation
> >> ascii-doc
> >>> pages in the main Ignite repo. However, the HTML version needs to
> reside
> >> on
> >>> the Ignite website, which is similar to the API docs. We can create
> tools
> >>> to do this in one click.
> >>>
> >>> Post-reviews are not prohibited in Apache, quite the opposite, and they
> >>> suit the documentation contribution process better. It's ok if
> committers
> >>> to the documentation merge the changes first and ask for a review later
> >> if
> >>> needed.
> >>>
> >>> -
> >>> Denis
> >>>
> >>>
> >>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
> >> [hidden email]>
> >>> wrote:
> >>>
> >>>> Pavel,
> >>>>
> >>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>> separate repo,
> >>>> Snippets are kept together with the docs, they /don't need/ to be
> stored
> >>>> in the main repo, although they can. They are compilable and up to
> date.
> >>>> I update the docs and API samples for features that hasn't been
> released
> >>>> in the GridGain docs and never thought it was a problem. I understand
> >>>> that you don't want to do extra work when adding code samples, but it
> >>>> looks like just an inconvenience. Let me suggest this: Let's think
> about
> >>>> a solution that will be comfortable for you, I'm pretty sure this
> >>>> inconvenience can be solved technically. But I need time to think it
> >>>> through.
> >>>>
> >>>>> we can't see the docs when doing global search (and/or replace) from
> >>>>> the IDE.
> >>>> I think you can add the docs repo to your IDE as a project. I used to
> do
> >>>> it in the beginning but then switched to Sublime Text, because it's
> more
> >>>> convenient to me. We are looking at it from different perspectives.
> I'm
> >>>> trying to create a process that is comfortable for tech writers rather
> >>>> than developers. And everybody has to accept some kind of a
> compromise:)
> >>>>
> >>>>>> Well, no one is able to "freely" commit code to Apache master, there
> >>>>>> is a process to follow - CI, reviews, etc.
> >>>>>> Same should happen for the docs, separate repo or not.
> >>>>>> But a separate repo will require separate ownership/management
> >>>>>> (probably?),
> >>>>>> but we already have everything in the main repo, why introduce
> >> overhead?
> >>>> Just think about it from my perspective. That creates a HUUUGE
> overhead
> >>>> for technical writers who work on the docs, and they are the ones who
> >>>> provide 90% of updates. I agree about the review process, and I'm
> going
> >>>> to think it over. But now it seems that we don't have to impose any
> >>>> strict process that impedes preparation of the docs.
> >>>>
> >>>> -Artem
> >>>>
> >>>>
> >>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
> >>>>>> all your pros points work just as well for a separate repository
> >>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>> separate repo,
> >>>>> we can't see the docs when doing global search (and/or replace) from
> >>>>> the IDE.
> >>>>>
> >>>>>> I am able to freely commit to master
> >>>>> Well, no one is able to "freely" commit code to Apache master, there
> >>>>> is a process to follow - CI, reviews, etc.
> >>>>> Same should happen for the docs, separate repo or not.
> >>>>> But a separate repo will require separate ownership/management
> >>>>> (probably?),
> >>>>> but we already have everything in the main repo, why introduce
> >> overhead?
> >>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> >>>>> <[hidden email] <mailto:[hidden email]>>
> >>>> wrote:
> >>>>>       Pavel,
> >>>>>
> >>>>>       As far as I can see, all your pros points work just as well
> for a
> >>>>>       separate repository (except for "everybody knows about it"). I
> >> don't
> >>>>>       mind keeping the docs in Ignite repo as long as I am able to
> >> freely
> >>>>>       commit to master. Will I be able to do that?
> >>>>>
> >>>>>       -Artem
> >>>>>
> >>>>>       On 23.06.2020 14:04, Pavel Tupitsyn wrote:
> >>>>>       > Ilya, Artem,
> >>>>>       >
> >>>>>       > "Separate repo just because we can't finish docs before
> release"
> >>>>>       > does not make sense to me. My proposal is:
> >>>>>       >
> >>>>>       > - Working version is in the master branch
> >>>>>       > - When a release branch is created, e.g. ignite-2.9, we
> create
> >>>>>       > ignite-2.9-docs and update it as long as we want.
> >>>>>       >
> >>>>>       > Pros (compared to a separate repo):
> >>>>>       > - Docs can be updated along with the code, same review
> process
> >>>>>       > - Visibility - everyone knows about main repo, docs are
> >>>>>       searchable together
> >>>>>       > with code in the IDE
> >>>>>       > - Code snippets can reference the actual code and we make
> sure
> >>>>>       they compile
> >>>>>       > - Code snippets can be tested on TC
> >>>>>       >
> >>>>>       > GridGain uses a separate repo for their docs, and it proved
> to
> >>>>>       be less than
> >>>>>       > optimal.
> >>>>>       > Especially when adding samples for new APIs which are not yet
> >>>>>       released.
> >>>>>       >
> >>>>>       >
> >>>>>       >
> >>>>>       > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
> >>>>>       <[hidden email] <mailto:
> [hidden email]
> >>>>>       > wrote:
> >>>>>       >
> >>>>>       >> Pavel,
> >>>>>       >>
> >>>>>       >> Yes, I mean a separate repository. The reason is that
> >>>>>       documentation is
> >>>>>       >> usually updated after the product version is released. As
> Ilya
> >>>>>       pointed
> >>>>>       >> out, keeping the docs in the main Ignite repository would
> >> entail
> >>>>>       >> completing the docs before the release date, which is not
> >>>>>       possible under
> >>>>>       >> current circumstances.
> >>>>>       >>
> >>>>>       >> Ilya,
> >>>>>       >>
> >>>>>       >> You can look at your company's documentation for a working
> >>>>>       prototype
> >>>>>       >> turned production-ready approach. The approach has been
> tested
> >>>>>       for a
> >>>>>       >> while and proved to be successful, at least with respect to
> our
> >>>>>       goals here.
> >>>>>       >>
> >>>>>       >> -Artem
> >>>>>       >>
> >>>>>       >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> >>>>>       >>> Hello!
> >>>>>       >>>
> >>>>>       >>> I'm not really sold on the github version yet, I would
> like to
> >>>>>       see a
> >>>>>       >>> prototype of such documentation before deciding, so for me
> >> it'w
> >>>>>       >>> 0
> >>>>>       >>>
> >>>>>       >>> Pavel, we don't have enough discipline to make sure that
> all
> >>>>>       >> documentation
> >>>>>       >>> is ready at the time of release, and we may need to add
> >>>>>       notices here and
> >>>>>       >>> there after a release is already out. This means, separate
> git
> >>>>>       >> repository,
> >>>>>       >>> or at least separate git tag on that repository, is needed.
> >>>>>       >>>
> >>>>>       >>> Regards,
> >>>>>
>

[dmagda]

Worked out well on my end. Thanks for sending the update!

How about the next step of taking the HTML and committing it to the website
repository? Did you have a chance to think through this step?

-
Denis


On Fri, Jul 17, 2020 at 5:27 AM Artem Budnikov <[hidden email]>
wrote:

> Hi everyone,
>
> I've prepared the initial set of source files for the Ignite
> documentation. If you are interested, you can take a look at
> https://github.com/apache/ignite/tree/IGNITE-7595/docs
>
> You can run a local web-server (jekyll) if you want to view the docs in
> your browser. Refer to the README.adoc for instructions. Some people had
> troubles installing Jekyll locally, so I added an instruction on how to
> use jekyll docker image.
>
> If you have any comments on the overall approach, please let me know.
> The styles and content are still a work in progress, so please don't
> report issues related to that.
>
> -Artem
>
> On 26.06.2020 01:54, Guru Stron wrote:
> > +1 for migrating docs to github. It will allow an easier contribution for
> > docs, I think. As a nice feature - adding an edit link (submit PR for
> docs)
> > to the document page on site.
> >
> > As for keeping them separate - Microsoft keeps docs for it's products in
> > separate repos, for example.
> >
> > On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <
> [hidden email]>
> > wrote:
> >
> >> OK, let's give it a try.
> >>
> >> The way I see it, the documentation source files will be located in the
> >> "/docs" folder, including UI templates/styles, asciidoc files, and build
> >> scripts. I'll start experimenting with this and will let you know when
> >> basic setup is ready.
> >>
> >> -Artem
> >>
> >> On 23.06.2020 20:19, Denis Magda wrote:
> >>> I believe that by keeping the documentation sources in the same
> >> repository
> >>> with the source code will help us to prepare and release all the
> release
> >>> artifacts at the same time. So, +1 for hosting raw documentation
> >> ascii-doc
> >>> pages in the main Ignite repo. However, the HTML version needs to
> reside
> >> on
> >>> the Ignite website, which is similar to the API docs. We can create
> tools
> >>> to do this in one click.
> >>>
> >>> Post-reviews are not prohibited in Apache, quite the opposite, and they
> >>> suit the documentation contribution process better. It's ok if
> committers
> >>> to the documentation merge the changes first and ask for a review later
> >> if
> >>> needed.
> >>>
> >>> -
> >>> Denis
> >>>
> >>>
> >>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
> >> [hidden email]>
> >>> wrote:
> >>>
> >>>> Pavel,
> >>>>
> >>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>> separate repo,
> >>>> Snippets are kept together with the docs, they /don't need/ to be
> stored
> >>>> in the main repo, although they can. They are compilable and up to
> date.
> >>>> I update the docs and API samples for features that hasn't been
> released
> >>>> in the GridGain docs and never thought it was a problem. I understand
> >>>> that you don't want to do extra work when adding code samples, but it
> >>>> looks like just an inconvenience. Let me suggest this: Let's think
> about
> >>>> a solution that will be comfortable for you, I'm pretty sure this
> >>>> inconvenience can be solved technically. But I need time to think it
> >>>> through.
> >>>>
> >>>>> we can't see the docs when doing global search (and/or replace) from
> >>>>> the IDE.
> >>>> I think you can add the docs repo to your IDE as a project. I used to
> do
> >>>> it in the beginning but then switched to Sublime Text, because it's
> more
> >>>> convenient to me. We are looking at it from different perspectives.
> I'm
> >>>> trying to create a process that is comfortable for tech writers rather
> >>>> than developers. And everybody has to accept some kind of a
> compromise:)
> >>>>
> >>>>>> Well, no one is able to "freely" commit code to Apache master, there
> >>>>>> is a process to follow - CI, reviews, etc.
> >>>>>> Same should happen for the docs, separate repo or not.
> >>>>>> But a separate repo will require separate ownership/management
> >>>>>> (probably?),
> >>>>>> but we already have everything in the main repo, why introduce
> >> overhead?
> >>>> Just think about it from my perspective. That creates a HUUUGE
> overhead
> >>>> for technical writers who work on the docs, and they are the ones who
> >>>> provide 90% of updates. I agree about the review process, and I'm
> going
> >>>> to think it over. But now it seems that we don't have to impose any
> >>>> strict process that impedes preparation of the docs.
> >>>>
> >>>> -Artem
> >>>>
> >>>>
> >>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
> >>>>>> all your pros points work just as well for a separate repository
> >>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>> separate repo,
> >>>>> we can't see the docs when doing global search (and/or replace) from
> >>>>> the IDE.
> >>>>>
> >>>>>> I am able to freely commit to master
> >>>>> Well, no one is able to "freely" commit code to Apache master, there
> >>>>> is a process to follow - CI, reviews, etc.
> >>>>> Same should happen for the docs, separate repo or not.
> >>>>> But a separate repo will require separate ownership/management
> >>>>> (probably?),
> >>>>> but we already have everything in the main repo, why introduce
> >> overhead?
> >>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> >>>>> <[hidden email] <mailto:[hidden email]>>
> >>>> wrote:
> >>>>>       Pavel,
> >>>>>
> >>>>>       As far as I can see, all your pros points work just as well
> for a
> >>>>>       separate repository (except for "everybody knows about it"). I
> >> don't
> >>>>>       mind keeping the docs in Ignite repo as long as I am able to
> >> freely
> >>>>>       commit to master. Will I be able to do that?
> >>>>>
> >>>>>       -Artem
> >>>>>
> >>>>>       On 23.06.2020 14:04, Pavel Tupitsyn wrote:
> >>>>>       > Ilya, Artem,
> >>>>>       >
> >>>>>       > "Separate repo just because we can't finish docs before
> release"
> >>>>>       > does not make sense to me. My proposal is:
> >>>>>       >
> >>>>>       > - Working version is in the master branch
> >>>>>       > - When a release branch is created, e.g. ignite-2.9, we
> create
> >>>>>       > ignite-2.9-docs and update it as long as we want.
> >>>>>       >
> >>>>>       > Pros (compared to a separate repo):
> >>>>>       > - Docs can be updated along with the code, same review
> process
> >>>>>       > - Visibility - everyone knows about main repo, docs are
> >>>>>       searchable together
> >>>>>       > with code in the IDE
> >>>>>       > - Code snippets can reference the actual code and we make
> sure
> >>>>>       they compile
> >>>>>       > - Code snippets can be tested on TC
> >>>>>       >
> >>>>>       > GridGain uses a separate repo for their docs, and it proved
> to
> >>>>>       be less than
> >>>>>       > optimal.
> >>>>>       > Especially when adding samples for new APIs which are not yet
> >>>>>       released.
> >>>>>       >
> >>>>>       >
> >>>>>       >
> >>>>>       > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
> >>>>>       <[hidden email] <mailto:
> [hidden email]
> >>>>>       > wrote:
> >>>>>       >
> >>>>>       >> Pavel,
> >>>>>       >>
> >>>>>       >> Yes, I mean a separate repository. The reason is that
> >>>>>       documentation is
> >>>>>       >> usually updated after the product version is released. As
> Ilya
> >>>>>       pointed
> >>>>>       >> out, keeping the docs in the main Ignite repository would
> >> entail
> >>>>>       >> completing the docs before the release date, which is not
> >>>>>       possible under
> >>>>>       >> current circumstances.
> >>>>>       >>
> >>>>>       >> Ilya,
> >>>>>       >>
> >>>>>       >> You can look at your company's documentation for a working
> >>>>>       prototype
> >>>>>       >> turned production-ready approach. The approach has been
> tested
> >>>>>       for a
> >>>>>       >> while and proved to be successful, at least with respect to
> our
> >>>>>       goals here.
> >>>>>       >>
> >>>>>       >> -Artem
> >>>>>       >>
> >>>>>       >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> >>>>>       >>> Hello!
> >>>>>       >>>
> >>>>>       >>> I'm not really sold on the github version yet, I would
> like to
> >>>>>       see a
> >>>>>       >>> prototype of such documentation before deciding, so for me
> >> it'w
> >>>>>       >>> 0
> >>>>>       >>>
> >>>>>       >>> Pavel, we don't have enough discipline to make sure that
> all
> >>>>>       >> documentation
> >>>>>       >>> is ready at the time of release, and we may need to add
> >>>>>       notices here and
> >>>>>       >>> there after a release is already out. This means, separate
> git
> >>>>>       >> repository,
> >>>>>       >>> or at least separate git tag on that repository, is needed.
> >>>>>       >>>
> >>>>>       >>> Regards,
> >>>>>
>

[Artem Budnikov]

Denis,

> How about the next step of taking the HTML and committing it to the website
> repository? Did you have a chance to think through this step?

Yes, I'll look into this this week. This shouldn't be very difficult.

-Artem

On 18.07.2020 00:43, Denis Magda wrote:

> Worked out well on my end. Thanks for sending the update!
>
> How about the next step of taking the HTML and committing it to the website
> repository? Did you have a chance to think through this step?
>
> -
> Denis
>
>
> On Fri, Jul 17, 2020 at 5:27 AM Artem Budnikov <[hidden email]>
> wrote:
>
>> Hi everyone,
>>
>> I've prepared the initial set of source files for the Ignite
>> documentation. If you are interested, you can take a look at
>> https://github.com/apache/ignite/tree/IGNITE-7595/docs
>>
>> You can run a local web-server (jekyll) if you want to view the docs in
>> your browser. Refer to the README.adoc for instructions. Some people had
>> troubles installing Jekyll locally, so I added an instruction on how to
>> use jekyll docker image.
>>
>> If you have any comments on the overall approach, please let me know.
>> The styles and content are still a work in progress, so please don't
>> report issues related to that.
>>
>> -Artem
>>
>> On 26.06.2020 01:54, Guru Stron wrote:
>>> +1 for migrating docs to github. It will allow an easier contribution for
>>> docs, I think. As a nice feature - adding an edit link (submit PR for
>> docs)
>>> to the document page on site.
>>>
>>> As for keeping them separate - Microsoft keeps docs for it's products in
>>> separate repos, for example.
>>>
>>> On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <
>> [hidden email]>
>>> wrote:
>>>
>>>> OK, let's give it a try.
>>>>
>>>> The way I see it, the documentation source files will be located in the
>>>> "/docs" folder, including UI templates/styles, asciidoc files, and build
>>>> scripts. I'll start experimenting with this and will let you know when
>>>> basic setup is ready.
>>>>
>>>> -Artem
>>>>
>>>> On 23.06.2020 20:19, Denis Magda wrote:
>>>>> I believe that by keeping the documentation sources in the same
>>>> repository
>>>>> with the source code will help us to prepare and release all the
>> release
>>>>> artifacts at the same time. So, +1 for hosting raw documentation
>>>> ascii-doc
>>>>> pages in the main Ignite repo. However, the HTML version needs to
>> reside
>>>> on
>>>>> the Ignite website, which is similar to the API docs. We can create
>> tools
>>>>> to do this in one click.
>>>>>
>>>>> Post-reviews are not prohibited in Apache, quite the opposite, and they
>>>>> suit the documentation contribution process better. It's ok if
>> committers
>>>>> to the documentation merge the changes first and ask for a review later
>>>> if
>>>>> needed.
>>>>>
>>>>> -
>>>>> Denis
>>>>>
>>>>>
>>>>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
>>>> [hidden email]>
>>>>> wrote:
>>>>>
>>>>>> Pavel,
>>>>>>
>>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>>>> separate repo,
>>>>>> Snippets are kept together with the docs, they /don't need/ to be
>> stored
>>>>>> in the main repo, although they can. They are compilable and up to
>> date.
>>>>>> I update the docs and API samples for features that hasn't been
>> released
>>>>>> in the GridGain docs and never thought it was a problem. I understand
>>>>>> that you don't want to do extra work when adding code samples, but it
>>>>>> looks like just an inconvenience. Let me suggest this: Let's think
>> about
>>>>>> a solution that will be comfortable for you, I'm pretty sure this
>>>>>> inconvenience can be solved technically. But I need time to think it
>>>>>> through.
>>>>>>
>>>>>>> we can't see the docs when doing global search (and/or replace) from
>>>>>>> the IDE.
>>>>>> I think you can add the docs repo to your IDE as a project. I used to
>> do
>>>>>> it in the beginning but then switched to Sublime Text, because it's
>> more
>>>>>> convenient to me. We are looking at it from different perspectives.
>> I'm
>>>>>> trying to create a process that is comfortable for tech writers rather
>>>>>> than developers. And everybody has to accept some kind of a
>> compromise:)
>>>>>>>> Well, no one is able to "freely" commit code to Apache master, there
>>>>>>>> is a process to follow - CI, reviews, etc.
>>>>>>>> Same should happen for the docs, separate repo or not.
>>>>>>>> But a separate repo will require separate ownership/management
>>>>>>>> (probably?),
>>>>>>>> but we already have everything in the main repo, why introduce
>>>> overhead?
>>>>>> Just think about it from my perspective. That creates a HUUUGE
>> overhead
>>>>>> for technical writers who work on the docs, and they are the ones who
>>>>>> provide 90% of updates. I agree about the review process, and I'm
>> going
>>>>>> to think it over. But now it seems that we don't have to impose any
>>>>>> strict process that impedes preparation of the docs.
>>>>>>
>>>>>> -Artem
>>>>>>
>>>>>>
>>>>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
>>>>>>>> all your pros points work just as well for a separate repository
>>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>>>> separate repo,
>>>>>>> we can't see the docs when doing global search (and/or replace) from
>>>>>>> the IDE.
>>>>>>>
>>>>>>>> I am able to freely commit to master
>>>>>>> Well, no one is able to "freely" commit code to Apache master, there
>>>>>>> is a process to follow - CI, reviews, etc.
>>>>>>> Same should happen for the docs, separate repo or not.
>>>>>>> But a separate repo will require separate ownership/management
>>>>>>> (probably?),
>>>>>>> but we already have everything in the main repo, why introduce
>>>> overhead?
>>>>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
>>>>>>> <[hidden email] <mailto:[hidden email]>>
>>>>>> wrote:
>>>>>>>        Pavel,
>>>>>>>
>>>>>>>        As far as I can see, all your pros points work just as well
>> for a
>>>>>>>        separate repository (except for "everybody knows about it"). I
>>>> don't
>>>>>>>        mind keeping the docs in Ignite repo as long as I am able to
>>>> freely
>>>>>>>        commit to master. Will I be able to do that?
>>>>>>>
>>>>>>>        -Artem
>>>>>>>
>>>>>>>        On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>>>>>>>        > Ilya, Artem,
>>>>>>>        >
>>>>>>>        > "Separate repo just because we can't finish docs before
>> release"
>>>>>>>        > does not make sense to me. My proposal is:
>>>>>>>        >
>>>>>>>        > - Working version is in the master branch
>>>>>>>        > - When a release branch is created, e.g. ignite-2.9, we
>> create
>>>>>>>        > ignite-2.9-docs and update it as long as we want.
>>>>>>>        >
>>>>>>>        > Pros (compared to a separate repo):
>>>>>>>        > - Docs can be updated along with the code, same review
>> process
>>>>>>>        > - Visibility - everyone knows about main repo, docs are
>>>>>>>        searchable together
>>>>>>>        > with code in the IDE
>>>>>>>        > - Code snippets can reference the actual code and we make
>> sure
>>>>>>>        they compile
>>>>>>>        > - Code snippets can be tested on TC
>>>>>>>        >
>>>>>>>        > GridGain uses a separate repo for their docs, and it proved
>> to
>>>>>>>        be less than
>>>>>>>        > optimal.
>>>>>>>        > Especially when adding samples for new APIs which are not yet
>>>>>>>        released.
>>>>>>>        >
>>>>>>>        >
>>>>>>>        >
>>>>>>>        > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>>>>>>>        <[hidden email] <mailto:
>> [hidden email]
>>>>>>>        > wrote:
>>>>>>>        >
>>>>>>>        >> Pavel,
>>>>>>>        >>
>>>>>>>        >> Yes, I mean a separate repository. The reason is that
>>>>>>>        documentation is
>>>>>>>        >> usually updated after the product version is released. As
>> Ilya
>>>>>>>        pointed
>>>>>>>        >> out, keeping the docs in the main Ignite repository would
>>>> entail
>>>>>>>        >> completing the docs before the release date, which is not
>>>>>>>        possible under
>>>>>>>        >> current circumstances.
>>>>>>>        >>
>>>>>>>        >> Ilya,
>>>>>>>        >>
>>>>>>>        >> You can look at your company's documentation for a working
>>>>>>>        prototype
>>>>>>>        >> turned production-ready approach. The approach has been
>> tested
>>>>>>>        for a
>>>>>>>        >> while and proved to be successful, at least with respect to
>> our
>>>>>>>        goals here.
>>>>>>>        >>
>>>>>>>        >> -Artem
>>>>>>>        >>
>>>>>>>        >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>>>>>>        >>> Hello!
>>>>>>>        >>>
>>>>>>>        >>> I'm not really sold on the github version yet, I would
>> like to
>>>>>>>        see a
>>>>>>>        >>> prototype of such documentation before deciding, so for me
>>>> it'w
>>>>>>>        >>> 0
>>>>>>>        >>>
>>>>>>>        >>> Pavel, we don't have enough discipline to make sure that
>> all
>>>>>>>        >> documentation
>>>>>>>        >>> is ready at the time of release, and we may need to add
>>>>>>>        notices here and
>>>>>>>        >>> there after a release is already out. This means, separate
>> git
>>>>>>>        >> repository,
>>>>>>>        >>> or at least separate git tag on that repository, is needed.
>>>>>>>        >>>
>>>>>>>        >>> Regards,
>>>>>>>

[Alexey Plekhanov]

Guys,

What about documentation for 2.9 release? Are we going to publish it on
readme.io or publish it on ignite.apache.org?
What about new edits? Should we still edit pages on readme.io or already
make changes in git repository?
Artem, could you please clarify the current documentation workflow?


пн, 20 июл. 2020 г. в 16:42, Artem Budnikov <[hidden email]>:

> Denis,
>
> > How about the next step of taking the HTML and committing it to the
> website
> > repository? Did you have a chance to think through this step?
>
> Yes, I'll look into this this week. This shouldn't be very difficult.
>
> -Artem
>
> On 18.07.2020 00:43, Denis Magda wrote:
> > Worked out well on my end. Thanks for sending the update!
> >
> > How about the next step of taking the HTML and committing it to the
> website
> > repository? Did you have a chance to think through this step?
> >
> > -
> > Denis
> >
> >
> > On Fri, Jul 17, 2020 at 5:27 AM Artem Budnikov <
> [hidden email]>
> > wrote:
> >
> >> Hi everyone,
> >>
> >> I've prepared the initial set of source files for the Ignite
> >> documentation. If you are interested, you can take a look at
> >> https://github.com/apache/ignite/tree/IGNITE-7595/docs
> >>
> >> You can run a local web-server (jekyll) if you want to view the docs in
> >> your browser. Refer to the README.adoc for instructions. Some people had
> >> troubles installing Jekyll locally, so I added an instruction on how to
> >> use jekyll docker image.
> >>
> >> If you have any comments on the overall approach, please let me know.
> >> The styles and content are still a work in progress, so please don't
> >> report issues related to that.
> >>
> >> -Artem
> >>
> >> On 26.06.2020 01:54, Guru Stron wrote:
> >>> +1 for migrating docs to github. It will allow an easier contribution
> for
> >>> docs, I think. As a nice feature - adding an edit link (submit PR for
> >> docs)
> >>> to the document page on site.
> >>>
> >>> As for keeping them separate - Microsoft keeps docs for it's products
> in
> >>> separate repos, for example.
> >>>
> >>> On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <
> >> [hidden email]>
> >>> wrote:
> >>>
> >>>> OK, let's give it a try.
> >>>>
> >>>> The way I see it, the documentation source files will be located in
> the
> >>>> "/docs" folder, including UI templates/styles, asciidoc files, and
> build
> >>>> scripts. I'll start experimenting with this and will let you know when
> >>>> basic setup is ready.
> >>>>
> >>>> -Artem
> >>>>
> >>>> On 23.06.2020 20:19, Denis Magda wrote:
> >>>>> I believe that by keeping the documentation sources in the same
> >>>> repository
> >>>>> with the source code will help us to prepare and release all the
> >> release
> >>>>> artifacts at the same time. So, +1 for hosting raw documentation
> >>>> ascii-doc
> >>>>> pages in the main Ignite repo. However, the HTML version needs to
> >> reside
> >>>> on
> >>>>> the Ignite website, which is similar to the API docs. We can create
> >> tools
> >>>>> to do this in one click.
> >>>>>
> >>>>> Post-reviews are not prohibited in Apache, quite the opposite, and
> they
> >>>>> suit the documentation contribution process better. It's ok if
> >> committers
> >>>>> to the documentation merge the changes first and ask for a review
> later
> >>>> if
> >>>>> needed.
> >>>>>
> >>>>> -
> >>>>> Denis
> >>>>>
> >>>>>
> >>>>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
> >>>> [hidden email]>
> >>>>> wrote:
> >>>>>
> >>>>>> Pavel,
> >>>>>>
> >>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>>>> separate repo,
> >>>>>> Snippets are kept together with the docs, they /don't need/ to be
> >> stored
> >>>>>> in the main repo, although they can. They are compilable and up to
> >> date.
> >>>>>> I update the docs and API samples for features that hasn't been
> >> released
> >>>>>> in the GridGain docs and never thought it was a problem. I
> understand
> >>>>>> that you don't want to do extra work when adding code samples, but
> it
> >>>>>> looks like just an inconvenience. Let me suggest this: Let's think
> >> about
> >>>>>> a solution that will be comfortable for you, I'm pretty sure this
> >>>>>> inconvenience can be solved technically. But I need time to think it
> >>>>>> through.
> >>>>>>
> >>>>>>> we can't see the docs when doing global search (and/or replace)
> from
> >>>>>>> the IDE.
> >>>>>> I think you can add the docs repo to your IDE as a project. I used
> to
> >> do
> >>>>>> it in the beginning but then switched to Sublime Text, because it's
> >> more
> >>>>>> convenient to me. We are looking at it from different perspectives.
> >> I'm
> >>>>>> trying to create a process that is comfortable for tech writers
> rather
> >>>>>> than developers. And everybody has to accept some kind of a
> >> compromise:)
> >>>>>>>> Well, no one is able to "freely" commit code to Apache master,
> there
> >>>>>>>> is a process to follow - CI, reviews, etc.
> >>>>>>>> Same should happen for the docs, separate repo or not.
> >>>>>>>> But a separate repo will require separate ownership/management
> >>>>>>>> (probably?),
> >>>>>>>> but we already have everything in the main repo, why introduce
> >>>> overhead?
> >>>>>> Just think about it from my perspective. That creates a HUUUGE
> >> overhead
> >>>>>> for technical writers who work on the docs, and they are the ones
> who
> >>>>>> provide 90% of updates. I agree about the review process, and I'm
> >> going
> >>>>>> to think it over. But now it seems that we don't have to impose any
> >>>>>> strict process that impedes preparation of the docs.
> >>>>>>
> >>>>>> -Artem
> >>>>>>
> >>>>>>
> >>>>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
> >>>>>>>> all your pros points work just as well for a separate repository
> >>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
> >>>>>>> separate repo,
> >>>>>>> we can't see the docs when doing global search (and/or replace)
> from
> >>>>>>> the IDE.
> >>>>>>>
> >>>>>>>> I am able to freely commit to master
> >>>>>>> Well, no one is able to "freely" commit code to Apache master,
> there
> >>>>>>> is a process to follow - CI, reviews, etc.
> >>>>>>> Same should happen for the docs, separate repo or not.
> >>>>>>> But a separate repo will require separate ownership/management
> >>>>>>> (probably?),
> >>>>>>> but we already have everything in the main repo, why introduce
> >>>> overhead?
> >>>>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
> >>>>>>> <[hidden email] <mailto:[hidden email]>>
> >>>>>> wrote:
> >>>>>>>        Pavel,
> >>>>>>>
> >>>>>>>        As far as I can see, all your pros points work just as well
> >> for a
> >>>>>>>        separate repository (except for "everybody knows about
> it"). I
> >>>> don't
> >>>>>>>        mind keeping the docs in Ignite repo as long as I am able to
> >>>> freely
> >>>>>>>        commit to master. Will I be able to do that?
> >>>>>>>
> >>>>>>>        -Artem
> >>>>>>>
> >>>>>>>        On 23.06.2020 14:04, Pavel Tupitsyn wrote:
> >>>>>>>        > Ilya, Artem,
> >>>>>>>        >
> >>>>>>>        > "Separate repo just because we can't finish docs before
> >> release"
> >>>>>>>        > does not make sense to me. My proposal is:
> >>>>>>>        >
> >>>>>>>        > - Working version is in the master branch
> >>>>>>>        > - When a release branch is created, e.g. ignite-2.9, we
> >> create
> >>>>>>>        > ignite-2.9-docs and update it as long as we want.
> >>>>>>>        >
> >>>>>>>        > Pros (compared to a separate repo):
> >>>>>>>        > - Docs can be updated along with the code, same review
> >> process
> >>>>>>>        > - Visibility - everyone knows about main repo, docs are
> >>>>>>>        searchable together
> >>>>>>>        > with code in the IDE
> >>>>>>>        > - Code snippets can reference the actual code and we make
> >> sure
> >>>>>>>        they compile
> >>>>>>>        > - Code snippets can be tested on TC
> >>>>>>>        >
> >>>>>>>        > GridGain uses a separate repo for their docs, and it
> proved
> >> to
> >>>>>>>        be less than
> >>>>>>>        > optimal.
> >>>>>>>        > Especially when adding samples for new APIs which are not
> yet
> >>>>>>>        released.
> >>>>>>>        >
> >>>>>>>        >
> >>>>>>>        >
> >>>>>>>        > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
> >>>>>>>        <[hidden email] <mailto:
> >> [hidden email]
> >>>>>>>        > wrote:
> >>>>>>>        >
> >>>>>>>        >> Pavel,
> >>>>>>>        >>
> >>>>>>>        >> Yes, I mean a separate repository. The reason is that
> >>>>>>>        documentation is
> >>>>>>>        >> usually updated after the product version is released. As
> >> Ilya
> >>>>>>>        pointed
> >>>>>>>        >> out, keeping the docs in the main Ignite repository would
> >>>> entail
> >>>>>>>        >> completing the docs before the release date, which is not
> >>>>>>>        possible under
> >>>>>>>        >> current circumstances.
> >>>>>>>        >>
> >>>>>>>        >> Ilya,
> >>>>>>>        >>
> >>>>>>>        >> You can look at your company's documentation for a
> working
> >>>>>>>        prototype
> >>>>>>>        >> turned production-ready approach. The approach has been
> >> tested
> >>>>>>>        for a
> >>>>>>>        >> while and proved to be successful, at least with respect
> to
> >> our
> >>>>>>>        goals here.
> >>>>>>>        >>
> >>>>>>>        >> -Artem
> >>>>>>>        >>
> >>>>>>>        >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
> >>>>>>>        >>> Hello!
> >>>>>>>        >>>
> >>>>>>>        >>> I'm not really sold on the github version yet, I would
> >> like to
> >>>>>>>        see a
> >>>>>>>        >>> prototype of such documentation before deciding, so for
> me
> >>>> it'w
> >>>>>>>        >>> 0
> >>>>>>>        >>>
> >>>>>>>        >>> Pavel, we don't have enough discipline to make sure that
> >> all
> >>>>>>>        >> documentation
> >>>>>>>        >>> is ready at the time of release, and we may need to add
> >>>>>>>        notices here and
> >>>>>>>        >>> there after a release is already out. This means,
> separate
> >> git
> >>>>>>>        >> repository,
> >>>>>>>        >>> or at least separate git tag on that repository, is
> needed.
> >>>>>>>        >>>
> >>>>>>>        >>> Regards,
> >>>>>>>
>

[Artem Budnikov]

Hi Alex,

Sorry, I missed this message. There is still a lot of work on the docs.
When is version 2.9 going to be released?

-Artem

On 22.07.2020 10:35, Alex Plehanov wrote:

> Guys,
>
> What about documentation for 2.9 release? Are we going to publish it on
> readme.io or publish it on ignite.apache.org?
> What about new edits? Should we still edit pages on readme.io or already
> make changes in git repository?
> Artem, could you please clarify the current documentation workflow?
>
>
> пн, 20 июл. 2020 г. в 16:42, Artem Budnikov <[hidden email]>:
>
>> Denis,
>>
>>> How about the next step of taking the HTML and committing it to the
>> website
>>> repository? Did you have a chance to think through this step?
>> Yes, I'll look into this this week. This shouldn't be very difficult.
>>
>> -Artem
>>
>> On 18.07.2020 00:43, Denis Magda wrote:
>>> Worked out well on my end. Thanks for sending the update!
>>>
>>> How about the next step of taking the HTML and committing it to the
>> website
>>> repository? Did you have a chance to think through this step?
>>>
>>> -
>>> Denis
>>>
>>>
>>> On Fri, Jul 17, 2020 at 5:27 AM Artem Budnikov <
>> [hidden email]>
>>> wrote:
>>>
>>>> Hi everyone,
>>>>
>>>> I've prepared the initial set of source files for the Ignite
>>>> documentation. If you are interested, you can take a look at
>>>> https://github.com/apache/ignite/tree/IGNITE-7595/docs
>>>>
>>>> You can run a local web-server (jekyll) if you want to view the docs in
>>>> your browser. Refer to the README.adoc for instructions. Some people had
>>>> troubles installing Jekyll locally, so I added an instruction on how to
>>>> use jekyll docker image.
>>>>
>>>> If you have any comments on the overall approach, please let me know.
>>>> The styles and content are still a work in progress, so please don't
>>>> report issues related to that.
>>>>
>>>> -Artem
>>>>
>>>> On 26.06.2020 01:54, Guru Stron wrote:
>>>>> +1 for migrating docs to github. It will allow an easier contribution
>> for
>>>>> docs, I think. As a nice feature - adding an edit link (submit PR for
>>>> docs)
>>>>> to the document page on site.
>>>>>
>>>>> As for keeping them separate - Microsoft keeps docs for it's products
>> in
>>>>> separate repos, for example.
>>>>>
>>>>> On Thu, 25 Jun 2020 at 15:48, Artem Budnikov <
>>>> [hidden email]>
>>>>> wrote:
>>>>>
>>>>>> OK, let's give it a try.
>>>>>>
>>>>>> The way I see it, the documentation source files will be located in
>> the
>>>>>> "/docs" folder, including UI templates/styles, asciidoc files, and
>> build
>>>>>> scripts. I'll start experimenting with this and will let you know when
>>>>>> basic setup is ready.
>>>>>>
>>>>>> -Artem
>>>>>>
>>>>>> On 23.06.2020 20:19, Denis Magda wrote:
>>>>>>> I believe that by keeping the documentation sources in the same
>>>>>> repository
>>>>>>> with the source code will help us to prepare and release all the
>>>> release
>>>>>>> artifacts at the same time. So, +1 for hosting raw documentation
>>>>>> ascii-doc
>>>>>>> pages in the main Ignite repo. However, the HTML version needs to
>>>> reside
>>>>>> on
>>>>>>> the Ignite website, which is similar to the API docs. We can create
>>>> tools
>>>>>>> to do this in one click.
>>>>>>>
>>>>>>> Post-reviews are not prohibited in Apache, quite the opposite, and
>> they
>>>>>>> suit the documentation contribution process better. It's ok if
>>>> committers
>>>>>>> to the documentation merge the changes first and ask for a review
>> later
>>>>>> if
>>>>>>> needed.
>>>>>>>
>>>>>>> -
>>>>>>> Denis
>>>>>>>
>>>>>>>
>>>>>>> On Tue, Jun 23, 2020 at 6:53 AM Artem Budnikov <
>>>>>> [hidden email]>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Pavel,
>>>>>>>>
>>>>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>>>>>> separate repo,
>>>>>>>> Snippets are kept together with the docs, they /don't need/ to be
>>>> stored
>>>>>>>> in the main repo, although they can. They are compilable and up to
>>>> date.
>>>>>>>> I update the docs and API samples for features that hasn't been
>>>> released
>>>>>>>> in the GridGain docs and never thought it was a problem. I
>> understand
>>>>>>>> that you don't want to do extra work when adding code samples, but
>> it
>>>>>>>> looks like just an inconvenience. Let me suggest this: Let's think
>>>> about
>>>>>>>> a solution that will be comfortable for you, I'm pretty sure this
>>>>>>>> inconvenience can be solved technically. But I need time to think it
>>>>>>>> through.
>>>>>>>>
>>>>>>>>> we can't see the docs when doing global search (and/or replace)
>> from
>>>>>>>>> the IDE.
>>>>>>>> I think you can add the docs repo to your IDE as a project. I used
>> to
>>>> do
>>>>>>>> it in the beginning but then switched to Sublime Text, because it's
>>>> more
>>>>>>>> convenient to me. We are looking at it from different perspectives.
>>>> I'm
>>>>>>>> trying to create a process that is comfortable for tech writers
>> rather
>>>>>>>> than developers. And everybody has to accept some kind of a
>>>> compromise:)
>>>>>>>>>> Well, no one is able to "freely" commit code to Apache master,
>> there
>>>>>>>>>> is a process to follow - CI, reviews, etc.
>>>>>>>>>> Same should happen for the docs, separate repo or not.
>>>>>>>>>> But a separate repo will require separate ownership/management
>>>>>>>>>> (probably?),
>>>>>>>>>> but we already have everything in the main repo, why introduce
>>>>>> overhead?
>>>>>>>> Just think about it from my perspective. That creates a HUUUGE
>>>> overhead
>>>>>>>> for technical writers who work on the docs, and they are the ones
>> who
>>>>>>>> provide 90% of updates. I agree about the review process, and I'm
>>>> going
>>>>>>>> to think it over. But now it seems that we don't have to impose any
>>>>>>>> strict process that impedes preparation of the docs.
>>>>>>>>
>>>>>>>> -Artem
>>>>>>>>
>>>>>>>>
>>>>>>>> On 23.06.2020 15:35, Pavel Tupitsyn wrote:
>>>>>>>>>> all your pros points work just as well for a separate repository
>>>>>>>>> I don't think so: we can't add snippets pointing to new APIs from a
>>>>>>>>> separate repo,
>>>>>>>>> we can't see the docs when doing global search (and/or replace)
>> from
>>>>>>>>> the IDE.
>>>>>>>>>
>>>>>>>>>> I am able to freely commit to master
>>>>>>>>> Well, no one is able to "freely" commit code to Apache master,
>> there
>>>>>>>>> is a process to follow - CI, reviews, etc.
>>>>>>>>> Same should happen for the docs, separate repo or not.
>>>>>>>>> But a separate repo will require separate ownership/management
>>>>>>>>> (probably?),
>>>>>>>>> but we already have everything in the main repo, why introduce
>>>>>> overhead?
>>>>>>>>> On Tue, Jun 23, 2020 at 2:59 PM Artem Budnikov
>>>>>>>>> <[hidden email] <mailto:[hidden email]>>
>>>>>>>> wrote:
>>>>>>>>>         Pavel,
>>>>>>>>>
>>>>>>>>>         As far as I can see, all your pros points work just as well
>>>> for a
>>>>>>>>>         separate repository (except for "everybody knows about
>> it"). I
>>>>>> don't
>>>>>>>>>         mind keeping the docs in Ignite repo as long as I am able to
>>>>>> freely
>>>>>>>>>         commit to master. Will I be able to do that?
>>>>>>>>>
>>>>>>>>>         -Artem
>>>>>>>>>
>>>>>>>>>         On 23.06.2020 14:04, Pavel Tupitsyn wrote:
>>>>>>>>>         > Ilya, Artem,
>>>>>>>>>         >
>>>>>>>>>         > "Separate repo just because we can't finish docs before
>>>> release"
>>>>>>>>>         > does not make sense to me. My proposal is:
>>>>>>>>>         >
>>>>>>>>>         > - Working version is in the master branch
>>>>>>>>>         > - When a release branch is created, e.g. ignite-2.9, we
>>>> create
>>>>>>>>>         > ignite-2.9-docs and update it as long as we want.
>>>>>>>>>         >
>>>>>>>>>         > Pros (compared to a separate repo):
>>>>>>>>>         > - Docs can be updated along with the code, same review
>>>> process
>>>>>>>>>         > - Visibility - everyone knows about main repo, docs are
>>>>>>>>>         searchable together
>>>>>>>>>         > with code in the IDE
>>>>>>>>>         > - Code snippets can reference the actual code and we make
>>>> sure
>>>>>>>>>         they compile
>>>>>>>>>         > - Code snippets can be tested on TC
>>>>>>>>>         >
>>>>>>>>>         > GridGain uses a separate repo for their docs, and it
>> proved
>>>> to
>>>>>>>>>         be less than
>>>>>>>>>         > optimal.
>>>>>>>>>         > Especially when adding samples for new APIs which are not
>> yet
>>>>>>>>>         released.
>>>>>>>>>         >
>>>>>>>>>         >
>>>>>>>>>         >
>>>>>>>>>         > On Tue, Jun 23, 2020 at 1:19 PM Artem Budnikov
>>>>>>>>>         <[hidden email] <mailto:
>>>> [hidden email]
>>>>>>>>>         > wrote:
>>>>>>>>>         >
>>>>>>>>>         >> Pavel,
>>>>>>>>>         >>
>>>>>>>>>         >> Yes, I mean a separate repository. The reason is that
>>>>>>>>>         documentation is
>>>>>>>>>         >> usually updated after the product version is released. As
>>>> Ilya
>>>>>>>>>         pointed
>>>>>>>>>         >> out, keeping the docs in the main Ignite repository would
>>>>>> entail
>>>>>>>>>         >> completing the docs before the release date, which is not
>>>>>>>>>         possible under
>>>>>>>>>         >> current circumstances.
>>>>>>>>>         >>
>>>>>>>>>         >> Ilya,
>>>>>>>>>         >>
>>>>>>>>>         >> You can look at your company's documentation for a
>> working
>>>>>>>>>         prototype
>>>>>>>>>         >> turned production-ready approach. The approach has been
>>>> tested
>>>>>>>>>         for a
>>>>>>>>>         >> while and proved to be successful, at least with respect
>> to
>>>> our
>>>>>>>>>         goals here.
>>>>>>>>>         >>
>>>>>>>>>         >> -Artem
>>>>>>>>>         >>
>>>>>>>>>         >> On 23.06.2020 12:48, Ilya Kasnacheev wrote:
>>>>>>>>>         >>> Hello!
>>>>>>>>>         >>>
>>>>>>>>>         >>> I'm not really sold on the github version yet, I would
>>>> like to
>>>>>>>>>         see a
>>>>>>>>>         >>> prototype of such documentation before deciding, so for
>> me
>>>>>> it'w
>>>>>>>>>         >>> 0
>>>>>>>>>         >>>
>>>>>>>>>         >>> Pavel, we don't have enough discipline to make sure that
>>>> all
>>>>>>>>>         >> documentation
>>>>>>>>>         >>> is ready at the time of release, and we may need to add
>>>>>>>>>         notices here and
>>>>>>>>>         >>> there after a release is already out. This means,
>> separate
>>>> git
>>>>>>>>>         >> repository,
>>>>>>>>>         >>> or at least separate git tag on that repository, is
>> needed.
>>>>>>>>>         >>>
>>>>>>>>>         >>> Regards,
>>>>>>>>>