Re: Moving Ignite documentation to github

[Maxim Muzafarov <mm...@apache.org>]

Artem,

I'd like to submit some documentation changes for 2.9 release. Should
I update docs on readme.io or publish it on ignite.apache.org?

On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
<a....@gmail.com> wrote:
>
> 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 <a....@gmail.com>:
> >
> >> 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 <
> >> a.budnikov.ignite@gmail.com>
> >>> 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 <
> >>>> a.budnikov.ignite@gmail.com>
> >>>>> 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 <
> >>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>> 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
> >>>>>>>>> <a.budnikov.ignite@gmail.com <ma...@gmail.com>>
> >>>>>>>> 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
> >>>>>>>>>         <a.budnikov.ignite@gmail.com <mailto:
> >>>> a.budnikov.ignite@gmail.com
> >>>>>>>>>         > 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,
> >>>>>>>>>

Re: Moving Ignite documentation to github

[Denis Magda <dm...@apache.org>]

Alex,

Thanks a lot for preparing the list. It's truly handy. We'll take care of
all the unassigned tickets by reaching out to the contributors.

-
Denis


On Thu, Aug 6, 2020 at 4:13 AM Alex Plehanov <pl...@gmail.com>
wrote:

> Artem,
>
> Ok, let's suggest edits for 2.9 release documentations via pull request to
> ignite-7595 branch if there are no other objections.
>
> чт, 6 авг. 2020 г. в 13:20, Artem Budnikov <a....@gmail.com>:
>
> > Alex,
> >
> > The documentation source files are still in the IGNITE-7595 branch. I
> > haven't pushed them to the master yet, but I can do so if it is
> > necessary. Or, you can add your changes to this branch. I added an
> > instruction on how to contribute:
> > https://github.com/apache/ignite/blob/IGNITE-7595/docs/README.adoc
> >
> > I suggest we do the first release of the new docs manually (just like we
> > do on readme.io) to get a sense of how the process works and how to
> > automate it better. Then, I'll document the entire process on our wiki.
> >
> > Sounds good?
> >
> > Artem
> >
> > On 06.08.2020 11:37, Alex Plehanov wrote:
> > > Denis, Artem,
> > >
> > > I've marked the "tracing" ticket as important.
> > > Also, I've added a new section to the release page [1] and created
> > > documentation tickets for some features. Now there is a documentation
> > > ticket exists for each important feature implemented in 2.9.
> > > I know that some Igniters are currently working on documentation, but
> the
> > > question is still unanswered: where to push changes? To GitHub, or to
> > > readme.io? Guys, can you clarify, please?
> > >
> > > [1]:
> > >
> >
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9
> > >
> > >
> > > вт, 4 авг. 2020 г. в 21:08, Denis Magda <dm...@apache.org>:
> > >
> > >> Hi Alex,
> > >>
> > >> Certainly, the new documentation should not be treated as a
> showstopper,
> > >> and if the code is ready much earlier, then we can release the docs on
> > >> readme.io.
> > >>
> > >> But, it's not clear what's the documentation readiness status. As per
> > our
> > >> updated release process, the docs need to be ready before the voting
> is
> > >> started [1]. That change was discussed and introduced after our
> > >> lessons-learned conversations related to the 2.8 release.
> > >>
> > >> Could you please help to figure out the status by preparing a list of
> > >> documentation tasks that must be completed before the voting time (all
> > >> significant features and changes)? The "most important tasks" section
> > [2]
> > >> already lists most of them, but the list might be incomplete. For
> > example,
> > >> the tracing feature should be added in 2.9, but it's not in the
> > important
> > >> tasks list. There might be something else profound that we should put
> on
> > >> paper.
> > >>
> > >> Once we get the list, we can start working with the contributors in
> > charge
> > >> to get things done. If some documentation pages won't be finished in 2
> > >> weeks from now, then it's reasonable to contribute the 2.9 docs to the
> > new
> > >> docs repository that will be ready for the release in 3-4 weeks. Just
> my
> > >> thinking.
> > >>
> > >> [1]
> > >>
> > >>
> >
> https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
> > >> [2]
> > >>
> > >>
> >
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks
> > >>
> > >> -
> > >> Denis
> > >>
> > >>
> > >> On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <plehanov.alex@gmail.com
> >
> > >> wrote:
> > >>
> > >>> Denis,
> > >>>
> > >>> We have some performance drop on benchmarks, so we need some time to
> > find
> > >>> problematic commit and analyze it. I hope this will be completed
> during
> > >> the
> > >>> current week and we move to the "Vote preparation" phase to the start
> > of
> > >>> next week.
> > >>> I think waiting for another month due to documentation it's too much.
> > >>> Do we have an option to release with documentation on readme.io and
> > then
> > >>> move documentation in the new format during next month?
> > >>>
> > >>>
> > >>>
> > >>> пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:
> > >>>
> > >>>> I would wait for 3-4 weeks and release the new docs in 2.9. It means
> > >> that
> > >>>> the release should be announced the first week of September which is
> > >> not
> > >>> a
> > >>>> huge slip. Moreover, it feels like the testing phase and release
> > >>> procedures
> > >>>> will not be completed sooner.
> > >>>>
> > >>>> So, I would suggest contributing 2.9 related page to the new
> > >>> documentation
> > >>>> repository.
> > >>>>
> > >>>>
> > >>>> Denis
> > >>>>
> > >>>> On Monday, August 3, 2020, Artem Budnikov <
> > a.budnikov.ignite@gmail.com
> > >>>> wrote:
> > >>>>
> > >>>>> Hi Maxim,
> > >>>>>
> > >>>>> The new docs project is not finished yet. There are still a lot of
> > >>> pages
> > >>>>> to port to the new format, and we are still working on the
> > >> integration
> > >>>> with
> > >>>>> the web-site. Nevertheless, we can try to publish the Ignite 2.9
> > >>>>> documentation on the web-site in the new format. The documentation
> > >> will
> > >>>> not
> > >>>>> be 100% complete, but it will be updated significantly and will
> > >> contain
> > >>>>> most of the information our users need. Actually, I would like to
> do
> > >>>> that,
> > >>>>> but it all depends on how much time I have before Ignite 2.9 is
> > >>> released.
> > >>>>> I'd say 2-3 weeks would be enough for me to finish all tasks that
> are
> > >>>>> critical for the publication.
> > >>>>>
> > >>>>> If we can wait with release 2.9 that much time, then I'll prepare
> the
> > >>>>> instruction on how to contribute to the docs.
> > >>>>>
> > >>>>> What do you think?
> > >>>>>
> > >>>>> -Artem
> > >>>>>
> > >>>>> On 03.08.2020 12:24, Maxim Muzafarov wrote:
> > >>>>>
> > >>>>>> Artem,
> > >>>>>>
> > >>>>>> I'd like to submit some documentation changes for 2.9 release.
> > >> Should
> > >>>>>> I update docs on readme.io or publish it on ignite.apache.org?
> > >>>>>>
> > >>>>>> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> > >>>>>> <a....@gmail.com> wrote:
> > >>>>>>
> > >>>>>>> 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 <
> > >>>>>>>> a.budnikov.ignite@gmail.com>:
> > >>>>>>>>
> > >>>>>>>> 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 <
> > >>>>>>>>>>
> > >>>>>>>>> a.budnikov.ignite@gmail.com>
> > >>>>>>>>>
> > >>>>>>>>>> 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 <
> > >>>>>>>>>>>>
> > >>>>>>>>>>> a.budnikov.ignite@gmail.com>
> > >>>>>>>>>>>
> > >>>>>>>>>>>> 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 <
> > >>>>>>>>>>>>>>
> > >>>>>>>>>>>>> a.budnikov.ignite@gmail.com>
> > >>>>>>>>>>>>>
> > >>>>>>>>>>>>>> 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
> > >>>>>>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:
> > >> a.budnikov.ignite@gmai
> > >>>>>>>>>>>>>>>> l.com>>
> > >>>>>>>>>>>>>>>>
> > >>>>>>>>>>>>>>> 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
> > >>>>>>>>>>>>>>>>           <a.budnikov.ignite@gmail.com <mailto:
> > >>>>>>>>>>>>>>>>
> > >>>>>>>>>>>>>>> a.budnikov.ignite@gmail.com
> > >>>>>>>>>>>>           > 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,
> > >>>>>>>>>>>>>>>>
> > >>>>>>>>>>>>>>>>
> > >>>> --
> > >>>> -
> > >>>> Denis
> > >>>>
> >
>

Re: Moving Ignite documentation to github

[Alex Plehanov <pl...@gmail.com>]

Artem,

Ok, let's suggest edits for 2.9 release documentations via pull request to
ignite-7595 branch if there are no other objections.

чт, 6 авг. 2020 г. в 13:20, Artem Budnikov <a....@gmail.com>:

> Alex,
>
> The documentation source files are still in the IGNITE-7595 branch. I
> haven't pushed them to the master yet, but I can do so if it is
> necessary. Or, you can add your changes to this branch. I added an
> instruction on how to contribute:
> https://github.com/apache/ignite/blob/IGNITE-7595/docs/README.adoc
>
> I suggest we do the first release of the new docs manually (just like we
> do on readme.io) to get a sense of how the process works and how to
> automate it better. Then, I'll document the entire process on our wiki.
>
> Sounds good?
>
> Artem
>
> On 06.08.2020 11:37, Alex Plehanov wrote:
> > Denis, Artem,
> >
> > I've marked the "tracing" ticket as important.
> > Also, I've added a new section to the release page [1] and created
> > documentation tickets for some features. Now there is a documentation
> > ticket exists for each important feature implemented in 2.9.
> > I know that some Igniters are currently working on documentation, but the
> > question is still unanswered: where to push changes? To GitHub, or to
> > readme.io? Guys, can you clarify, please?
> >
> > [1]:
> >
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9
> >
> >
> > вт, 4 авг. 2020 г. в 21:08, Denis Magda <dm...@apache.org>:
> >
> >> Hi Alex,
> >>
> >> Certainly, the new documentation should not be treated as a showstopper,
> >> and if the code is ready much earlier, then we can release the docs on
> >> readme.io.
> >>
> >> But, it's not clear what's the documentation readiness status. As per
> our
> >> updated release process, the docs need to be ready before the voting is
> >> started [1]. That change was discussed and introduced after our
> >> lessons-learned conversations related to the 2.8 release.
> >>
> >> Could you please help to figure out the status by preparing a list of
> >> documentation tasks that must be completed before the voting time (all
> >> significant features and changes)? The "most important tasks" section
> [2]
> >> already lists most of them, but the list might be incomplete. For
> example,
> >> the tracing feature should be added in 2.9, but it's not in the
> important
> >> tasks list. There might be something else profound that we should put on
> >> paper.
> >>
> >> Once we get the list, we can start working with the contributors in
> charge
> >> to get things done. If some documentation pages won't be finished in 2
> >> weeks from now, then it's reasonable to contribute the 2.9 docs to the
> new
> >> docs repository that will be ready for the release in 3-4 weeks. Just my
> >> thinking.
> >>
> >> [1]
> >>
> >>
> https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
> >> [2]
> >>
> >>
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks
> >>
> >> -
> >> Denis
> >>
> >>
> >> On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <pl...@gmail.com>
> >> wrote:
> >>
> >>> Denis,
> >>>
> >>> We have some performance drop on benchmarks, so we need some time to
> find
> >>> problematic commit and analyze it. I hope this will be completed during
> >> the
> >>> current week and we move to the "Vote preparation" phase to the start
> of
> >>> next week.
> >>> I think waiting for another month due to documentation it's too much.
> >>> Do we have an option to release with documentation on readme.io and
> then
> >>> move documentation in the new format during next month?
> >>>
> >>>
> >>>
> >>> пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:
> >>>
> >>>> I would wait for 3-4 weeks and release the new docs in 2.9. It means
> >> that
> >>>> the release should be announced the first week of September which is
> >> not
> >>> a
> >>>> huge slip. Moreover, it feels like the testing phase and release
> >>> procedures
> >>>> will not be completed sooner.
> >>>>
> >>>> So, I would suggest contributing 2.9 related page to the new
> >>> documentation
> >>>> repository.
> >>>>
> >>>>
> >>>> Denis
> >>>>
> >>>> On Monday, August 3, 2020, Artem Budnikov <
> a.budnikov.ignite@gmail.com
> >>>> wrote:
> >>>>
> >>>>> Hi Maxim,
> >>>>>
> >>>>> The new docs project is not finished yet. There are still a lot of
> >>> pages
> >>>>> to port to the new format, and we are still working on the
> >> integration
> >>>> with
> >>>>> the web-site. Nevertheless, we can try to publish the Ignite 2.9
> >>>>> documentation on the web-site in the new format. The documentation
> >> will
> >>>> not
> >>>>> be 100% complete, but it will be updated significantly and will
> >> contain
> >>>>> most of the information our users need. Actually, I would like to do
> >>>> that,
> >>>>> but it all depends on how much time I have before Ignite 2.9 is
> >>> released.
> >>>>> I'd say 2-3 weeks would be enough for me to finish all tasks that are
> >>>>> critical for the publication.
> >>>>>
> >>>>> If we can wait with release 2.9 that much time, then I'll prepare the
> >>>>> instruction on how to contribute to the docs.
> >>>>>
> >>>>> What do you think?
> >>>>>
> >>>>> -Artem
> >>>>>
> >>>>> On 03.08.2020 12:24, Maxim Muzafarov wrote:
> >>>>>
> >>>>>> Artem,
> >>>>>>
> >>>>>> I'd like to submit some documentation changes for 2.9 release.
> >> Should
> >>>>>> I update docs on readme.io or publish it on ignite.apache.org?
> >>>>>>
> >>>>>> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> >>>>>> <a....@gmail.com> wrote:
> >>>>>>
> >>>>>>> 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 <
> >>>>>>>> a.budnikov.ignite@gmail.com>:
> >>>>>>>>
> >>>>>>>> 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 <
> >>>>>>>>>>
> >>>>>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>>>>
> >>>>>>>>>> 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 <
> >>>>>>>>>>>>
> >>>>>>>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>>>>>>
> >>>>>>>>>>>> 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 <
> >>>>>>>>>>>>>>
> >>>>>>>>>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>>>>>>>>
> >>>>>>>>>>>>>> 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
> >>>>>>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:
> >> a.budnikov.ignite@gmai
> >>>>>>>>>>>>>>>> l.com>>
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> 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
> >>>>>>>>>>>>>>>>           <a.budnikov.ignite@gmail.com <mailto:
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> a.budnikov.ignite@gmail.com
> >>>>>>>>>>>>           > 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,
> >>>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>>>
> >>>> --
> >>>> -
> >>>> Denis
> >>>>
>

Re: Moving Ignite documentation to github

[Artem Budnikov <a....@gmail.com>]

Alex,

The documentation source files are still in the IGNITE-7595 branch. I 
haven't pushed them to the master yet, but I can do so if it is 
necessary. Or, you can add your changes to this branch. I added an 
instruction on how to contribute: 
https://github.com/apache/ignite/blob/IGNITE-7595/docs/README.adoc

I suggest we do the first release of the new docs manually (just like we 
do on readme.io) to get a sense of how the process works and how to 
automate it better. Then, I'll document the entire process on our wiki.

Sounds good?

Artem

On 06.08.2020 11:37, Alex Plehanov wrote:
> Denis, Artem,
>
> I've marked the "tracing" ticket as important.
> Also, I've added a new section to the release page [1] and created
> documentation tickets for some features. Now there is a documentation
> ticket exists for each important feature implemented in 2.9.
> I know that some Igniters are currently working on documentation, but the
> question is still unanswered: where to push changes? To GitHub, or to
> readme.io? Guys, can you clarify, please?
>
> [1]:
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9
>
>
> вт, 4 авг. 2020 г. в 21:08, Denis Magda <dm...@apache.org>:
>
>> Hi Alex,
>>
>> Certainly, the new documentation should not be treated as a showstopper,
>> and if the code is ready much earlier, then we can release the docs on
>> readme.io.
>>
>> But, it's not clear what's the documentation readiness status. As per our
>> updated release process, the docs need to be ready before the voting is
>> started [1]. That change was discussed and introduced after our
>> lessons-learned conversations related to the 2.8 release.
>>
>> Could you please help to figure out the status by preparing a list of
>> documentation tasks that must be completed before the voting time (all
>> significant features and changes)? The "most important tasks" section [2]
>> already lists most of them, but the list might be incomplete. For example,
>> the tracing feature should be added in 2.9, but it's not in the important
>> tasks list. There might be something else profound that we should put on
>> paper.
>>
>> Once we get the list, we can start working with the contributors in charge
>> to get things done. If some documentation pages won't be finished in 2
>> weeks from now, then it's reasonable to contribute the 2.9 docs to the new
>> docs repository that will be ready for the release in 3-4 weeks. Just my
>> thinking.
>>
>> [1]
>>
>> https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
>> [2]
>>
>> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks
>>
>> -
>> Denis
>>
>>
>> On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <pl...@gmail.com>
>> wrote:
>>
>>> Denis,
>>>
>>> We have some performance drop on benchmarks, so we need some time to find
>>> problematic commit and analyze it. I hope this will be completed during
>> the
>>> current week and we move to the "Vote preparation" phase to the start of
>>> next week.
>>> I think waiting for another month due to documentation it's too much.
>>> Do we have an option to release with documentation on readme.io and then
>>> move documentation in the new format during next month?
>>>
>>>
>>>
>>> пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:
>>>
>>>> I would wait for 3-4 weeks and release the new docs in 2.9. It means
>> that
>>>> the release should be announced the first week of September which is
>> not
>>> a
>>>> huge slip. Moreover, it feels like the testing phase and release
>>> procedures
>>>> will not be completed sooner.
>>>>
>>>> So, I would suggest contributing 2.9 related page to the new
>>> documentation
>>>> repository.
>>>>
>>>>
>>>> Denis
>>>>
>>>> On Monday, August 3, 2020, Artem Budnikov <a.budnikov.ignite@gmail.com
>>>> wrote:
>>>>
>>>>> Hi Maxim,
>>>>>
>>>>> The new docs project is not finished yet. There are still a lot of
>>> pages
>>>>> to port to the new format, and we are still working on the
>> integration
>>>> with
>>>>> the web-site. Nevertheless, we can try to publish the Ignite 2.9
>>>>> documentation on the web-site in the new format. The documentation
>> will
>>>> not
>>>>> be 100% complete, but it will be updated significantly and will
>> contain
>>>>> most of the information our users need. Actually, I would like to do
>>>> that,
>>>>> but it all depends on how much time I have before Ignite 2.9 is
>>> released.
>>>>> I'd say 2-3 weeks would be enough for me to finish all tasks that are
>>>>> critical for the publication.
>>>>>
>>>>> If we can wait with release 2.9 that much time, then I'll prepare the
>>>>> instruction on how to contribute to the docs.
>>>>>
>>>>> What do you think?
>>>>>
>>>>> -Artem
>>>>>
>>>>> On 03.08.2020 12:24, Maxim Muzafarov wrote:
>>>>>
>>>>>> Artem,
>>>>>>
>>>>>> I'd like to submit some documentation changes for 2.9 release.
>> Should
>>>>>> I update docs on readme.io or publish it on ignite.apache.org?
>>>>>>
>>>>>> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
>>>>>> <a....@gmail.com> wrote:
>>>>>>
>>>>>>> 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 <
>>>>>>>> a.budnikov.ignite@gmail.com>:
>>>>>>>>
>>>>>>>> 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 <
>>>>>>>>>>
>>>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>>>
>>>>>>>>>> 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 <
>>>>>>>>>>>>
>>>>>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>>>>>
>>>>>>>>>>>> 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 <
>>>>>>>>>>>>>>
>>>>>>>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>>>>>>>
>>>>>>>>>>>>>> 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
>>>>>>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:
>> a.budnikov.ignite@gmai
>>>>>>>>>>>>>>>> l.com>>
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> 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
>>>>>>>>>>>>>>>>           <a.budnikov.ignite@gmail.com <mailto:
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> a.budnikov.ignite@gmail.com
>>>>>>>>>>>>           > 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,
>>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>>>
>>>> --
>>>> -
>>>> Denis
>>>>

Re: Moving Ignite documentation to github

[Alex Plehanov <pl...@gmail.com>]

Denis, Artem,

I've marked the "tracing" ticket as important.
Also, I've added a new section to the release page [1] and created
documentation tickets for some features. Now there is a documentation
ticket exists for each important feature implemented in 2.9.
I know that some Igniters are currently working on documentation, but the
question is still unanswered: where to push changes? To GitHub, or to
readme.io? Guys, can you clarify, please?

[1]:
https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9


вт, 4 авг. 2020 г. в 21:08, Denis Magda <dm...@apache.org>:

> Hi Alex,
>
> Certainly, the new documentation should not be treated as a showstopper,
> and if the code is ready much earlier, then we can release the docs on
> readme.io.
>
> But, it's not clear what's the documentation readiness status. As per our
> updated release process, the docs need to be ready before the voting is
> started [1]. That change was discussed and introduced after our
> lessons-learned conversations related to the 2.8 release.
>
> Could you please help to figure out the status by preparing a list of
> documentation tasks that must be completed before the voting time (all
> significant features and changes)? The "most important tasks" section [2]
> already lists most of them, but the list might be incomplete. For example,
> the tracing feature should be added in 2.9, but it's not in the important
> tasks list. There might be something else profound that we should put on
> paper.
>
> Once we get the list, we can start working with the contributors in charge
> to get things done. If some documentation pages won't be finished in 2
> weeks from now, then it's reasonable to contribute the 2.9 docs to the new
> docs repository that will be ready for the release in 3-4 weeks. Just my
> thinking.
>
> [1]
>
> https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
> [2]
>
> https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks
>
> -
> Denis
>
>
> On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <pl...@gmail.com>
> wrote:
>
> > Denis,
> >
> > We have some performance drop on benchmarks, so we need some time to find
> > problematic commit and analyze it. I hope this will be completed during
> the
> > current week and we move to the "Vote preparation" phase to the start of
> > next week.
> > I think waiting for another month due to documentation it's too much.
> > Do we have an option to release with documentation on readme.io and then
> > move documentation in the new format during next month?
> >
> >
> >
> > пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:
> >
> > > I would wait for 3-4 weeks and release the new docs in 2.9. It means
> that
> > > the release should be announced the first week of September which is
> not
> > a
> > > huge slip. Moreover, it feels like the testing phase and release
> > procedures
> > > will not be completed sooner.
> > >
> > > So, I would suggest contributing 2.9 related page to the new
> > documentation
> > > repository.
> > >
> > >
> > > Denis
> > >
> > > On Monday, August 3, 2020, Artem Budnikov <a.budnikov.ignite@gmail.com
> >
> > > wrote:
> > >
> > > > Hi Maxim,
> > > >
> > > > The new docs project is not finished yet. There are still a lot of
> > pages
> > > > to port to the new format, and we are still working on the
> integration
> > > with
> > > > the web-site. Nevertheless, we can try to publish the Ignite 2.9
> > > > documentation on the web-site in the new format. The documentation
> will
> > > not
> > > > be 100% complete, but it will be updated significantly and will
> contain
> > > > most of the information our users need. Actually, I would like to do
> > > that,
> > > > but it all depends on how much time I have before Ignite 2.9 is
> > released.
> > > > I'd say 2-3 weeks would be enough for me to finish all tasks that are
> > > > critical for the publication.
> > > >
> > > > If we can wait with release 2.9 that much time, then I'll prepare the
> > > > instruction on how to contribute to the docs.
> > > >
> > > > What do you think?
> > > >
> > > > -Artem
> > > >
> > > > On 03.08.2020 12:24, Maxim Muzafarov wrote:
> > > >
> > > >> Artem,
> > > >>
> > > >> I'd like to submit some documentation changes for 2.9 release.
> Should
> > > >> I update docs on readme.io or publish it on ignite.apache.org?
> > > >>
> > > >> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> > > >> <a....@gmail.com> wrote:
> > > >>
> > > >>> 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 <
> > > >>>> a.budnikov.ignite@gmail.com>:
> > > >>>>
> > > >>>> 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 <
> > > >>>>>>
> > > >>>>> a.budnikov.ignite@gmail.com>
> > > >>>>>
> > > >>>>>> 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 <
> > > >>>>>>>>
> > > >>>>>>> a.budnikov.ignite@gmail.com>
> > > >>>>>>>
> > > >>>>>>>> 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 <
> > > >>>>>>>>>>
> > > >>>>>>>>> a.budnikov.ignite@gmail.com>
> > > >>>>>>>>>
> > > >>>>>>>>>> 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
> > > >>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:
> a.budnikov.ignite@gmai
> > > >>>>>>>>>>>> l.com>>
> > > >>>>>>>>>>>>
> > > >>>>>>>>>>> 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
> > > >>>>>>>>>>>>          <a.budnikov.ignite@gmail.com <mailto:
> > > >>>>>>>>>>>>
> > > >>>>>>>>>>> a.budnikov.ignite@gmail.com
> > > >>>>>>>
> > > >>>>>>>>          > 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,
> > > >>>>>>>>>>>>
> > > >>>>>>>>>>>>
> > >
> > > --
> > > -
> > > Denis
> > >
> >
>

Re: Moving Ignite documentation to github

[Denis Magda <dm...@apache.org>]

Hi Alex,

Certainly, the new documentation should not be treated as a showstopper,
and if the code is ready much earlier, then we can release the docs on
readme.io.

But, it's not clear what's the documentation readiness status. As per our
updated release process, the docs need to be ready before the voting is
started [1]. That change was discussed and introduced after our
lessons-learned conversations related to the 2.8 release.

Could you please help to figure out the status by preparing a list of
documentation tasks that must be completed before the voting time (all
significant features and changes)? The "most important tasks" section [2]
already lists most of them, but the list might be incomplete. For example,
the tracing feature should be added in 2.9, but it's not in the important
tasks list. There might be something else profound that we should put on
paper.

Once we get the list, we can start working with the contributors in charge
to get things done. If some documentation pages won't be finished in 2
weeks from now, then it's reasonable to contribute the 2.9 docs to the new
docs repository that will be ready for the release in 3-4 weeks. Just my
thinking.

[1]
https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
[2]
https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks

-
Denis


On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <pl...@gmail.com>
wrote:

> Denis,
>
> We have some performance drop on benchmarks, so we need some time to find
> problematic commit and analyze it. I hope this will be completed during the
> current week and we move to the "Vote preparation" phase to the start of
> next week.
> I think waiting for another month due to documentation it's too much.
> Do we have an option to release with documentation on readme.io and then
> move documentation in the new format during next month?
>
>
>
> пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:
>
> > I would wait for 3-4 weeks and release the new docs in 2.9. It means that
> > the release should be announced the first week of September which is not
> a
> > huge slip. Moreover, it feels like the testing phase and release
> procedures
> > will not be completed sooner.
> >
> > So, I would suggest contributing 2.9 related page to the new
> documentation
> > repository.
> >
> >
> > Denis
> >
> > On Monday, August 3, 2020, Artem Budnikov <a....@gmail.com>
> > wrote:
> >
> > > Hi Maxim,
> > >
> > > The new docs project is not finished yet. There are still a lot of
> pages
> > > to port to the new format, and we are still working on the integration
> > with
> > > the web-site. Nevertheless, we can try to publish the Ignite 2.9
> > > documentation on the web-site in the new format. The documentation will
> > not
> > > be 100% complete, but it will be updated significantly and will contain
> > > most of the information our users need. Actually, I would like to do
> > that,
> > > but it all depends on how much time I have before Ignite 2.9 is
> released.
> > > I'd say 2-3 weeks would be enough for me to finish all tasks that are
> > > critical for the publication.
> > >
> > > If we can wait with release 2.9 that much time, then I'll prepare the
> > > instruction on how to contribute to the docs.
> > >
> > > What do you think?
> > >
> > > -Artem
> > >
> > > On 03.08.2020 12:24, Maxim Muzafarov wrote:
> > >
> > >> Artem,
> > >>
> > >> I'd like to submit some documentation changes for 2.9 release. Should
> > >> I update docs on readme.io or publish it on ignite.apache.org?
> > >>
> > >> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> > >> <a....@gmail.com> wrote:
> > >>
> > >>> 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 <
> > >>>> a.budnikov.ignite@gmail.com>:
> > >>>>
> > >>>> 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 <
> > >>>>>>
> > >>>>> a.budnikov.ignite@gmail.com>
> > >>>>>
> > >>>>>> 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 <
> > >>>>>>>>
> > >>>>>>> a.budnikov.ignite@gmail.com>
> > >>>>>>>
> > >>>>>>>> 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 <
> > >>>>>>>>>>
> > >>>>>>>>> a.budnikov.ignite@gmail.com>
> > >>>>>>>>>
> > >>>>>>>>>> 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
> > >>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:a.budnikov.ignite@gmai
> > >>>>>>>>>>>> l.com>>
> > >>>>>>>>>>>>
> > >>>>>>>>>>> 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
> > >>>>>>>>>>>>          <a.budnikov.ignite@gmail.com <mailto:
> > >>>>>>>>>>>>
> > >>>>>>>>>>> a.budnikov.ignite@gmail.com
> > >>>>>>>
> > >>>>>>>>          > 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,
> > >>>>>>>>>>>>
> > >>>>>>>>>>>>
> >
> > --
> > -
> > Denis
> >
>

Re: Moving Ignite documentation to github

[Alex Plehanov <pl...@gmail.com>]

Denis,

We have some performance drop on benchmarks, so we need some time to find
problematic commit and analyze it. I hope this will be completed during the
current week and we move to the "Vote preparation" phase to the start of
next week.
I think waiting for another month due to documentation it's too much.
Do we have an option to release with documentation on readme.io and then
move documentation in the new format during next month?



пн, 3 авг. 2020 г. в 17:55, Denis Magda <dm...@apache.org>:

> I would wait for 3-4 weeks and release the new docs in 2.9. It means that
> the release should be announced the first week of September which is not a
> huge slip. Moreover, it feels like the testing phase and release procedures
> will not be completed sooner.
>
> So, I would suggest contributing 2.9 related page to the new documentation
> repository.
>
>
> Denis
>
> On Monday, August 3, 2020, Artem Budnikov <a....@gmail.com>
> wrote:
>
> > Hi Maxim,
> >
> > The new docs project is not finished yet. There are still a lot of pages
> > to port to the new format, and we are still working on the integration
> with
> > the web-site. Nevertheless, we can try to publish the Ignite 2.9
> > documentation on the web-site in the new format. The documentation will
> not
> > be 100% complete, but it will be updated significantly and will contain
> > most of the information our users need. Actually, I would like to do
> that,
> > but it all depends on how much time I have before Ignite 2.9 is released.
> > I'd say 2-3 weeks would be enough for me to finish all tasks that are
> > critical for the publication.
> >
> > If we can wait with release 2.9 that much time, then I'll prepare the
> > instruction on how to contribute to the docs.
> >
> > What do you think?
> >
> > -Artem
> >
> > On 03.08.2020 12:24, Maxim Muzafarov wrote:
> >
> >> Artem,
> >>
> >> I'd like to submit some documentation changes for 2.9 release. Should
> >> I update docs on readme.io or publish it on ignite.apache.org?
> >>
> >> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> >> <a....@gmail.com> wrote:
> >>
> >>> 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 <
> >>>> a.budnikov.ignite@gmail.com>:
> >>>>
> >>>> 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 <
> >>>>>>
> >>>>> a.budnikov.ignite@gmail.com>
> >>>>>
> >>>>>> 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 <
> >>>>>>>>
> >>>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>>
> >>>>>>>> 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 <
> >>>>>>>>>>
> >>>>>>>>> a.budnikov.ignite@gmail.com>
> >>>>>>>>>
> >>>>>>>>>> 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
> >>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:a.budnikov.ignite@gmai
> >>>>>>>>>>>> l.com>>
> >>>>>>>>>>>>
> >>>>>>>>>>> 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
> >>>>>>>>>>>>          <a.budnikov.ignite@gmail.com <mailto:
> >>>>>>>>>>>>
> >>>>>>>>>>> a.budnikov.ignite@gmail.com
> >>>>>>>
> >>>>>>>>          > 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,
> >>>>>>>>>>>>
> >>>>>>>>>>>>
>
> --
> -
> Denis
>

Re: Moving Ignite documentation to github

[Denis Magda <dm...@apache.org>]

I would wait for 3-4 weeks and release the new docs in 2.9. It means that
the release should be announced the first week of September which is not a
huge slip. Moreover, it feels like the testing phase and release procedures
will not be completed sooner.

So, I would suggest contributing 2.9 related page to the new documentation
repository.


Denis

On Monday, August 3, 2020, Artem Budnikov <a....@gmail.com>
wrote:

> Hi Maxim,
>
> The new docs project is not finished yet. There are still a lot of pages
> to port to the new format, and we are still working on the integration with
> the web-site. Nevertheless, we can try to publish the Ignite 2.9
> documentation on the web-site in the new format. The documentation will not
> be 100% complete, but it will be updated significantly and will contain
> most of the information our users need. Actually, I would like to do that,
> but it all depends on how much time I have before Ignite 2.9 is released.
> I'd say 2-3 weeks would be enough for me to finish all tasks that are
> critical for the publication.
>
> If we can wait with release 2.9 that much time, then I'll prepare the
> instruction on how to contribute to the docs.
>
> What do you think?
>
> -Artem
>
> On 03.08.2020 12:24, Maxim Muzafarov wrote:
>
>> Artem,
>>
>> I'd like to submit some documentation changes for 2.9 release. Should
>> I update docs on readme.io or publish it on ignite.apache.org?
>>
>> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
>> <a....@gmail.com> wrote:
>>
>>> 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 <
>>>> a.budnikov.ignite@gmail.com>:
>>>>
>>>> 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 <
>>>>>>
>>>>> a.budnikov.ignite@gmail.com>
>>>>>
>>>>>> 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 <
>>>>>>>>
>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>
>>>>>>>> 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 <
>>>>>>>>>>
>>>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>>>
>>>>>>>>>> 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
>>>>>>>>>>>> <a.budnikov.ignite@gmail.com <mailto:a.budnikov.ignite@gmai
>>>>>>>>>>>> l.com>>
>>>>>>>>>>>>
>>>>>>>>>>> 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
>>>>>>>>>>>>          <a.budnikov.ignite@gmail.com <mailto:
>>>>>>>>>>>>
>>>>>>>>>>> a.budnikov.ignite@gmail.com
>>>>>>>
>>>>>>>>          > 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,
>>>>>>>>>>>>
>>>>>>>>>>>>

-- 
-
Denis

Re: Moving Ignite documentation to github

[Artem Budnikov <a....@gmail.com>]

Hi Maxim,

The new docs project is not finished yet. There are still a lot of pages 
to port to the new format, and we are still working on the integration 
with the web-site. Nevertheless, we can try to publish the Ignite 2.9 
documentation on the web-site in the new format. The documentation will 
not be 100% complete, but it will be updated significantly and will 
contain most of the information our users need. Actually, I would like 
to do that, but it all depends on how much time I have before Ignite 2.9 
is released. I'd say 2-3 weeks would be enough for me to finish all 
tasks that are critical for the publication.

If we can wait with release 2.9 that much time, then I'll prepare the 
instruction on how to contribute to the docs.

What do you think?

-Artem

On 03.08.2020 12:24, Maxim Muzafarov wrote:
> Artem,
>
> I'd like to submit some documentation changes for 2.9 release. Should
> I update docs on readme.io or publish it on ignite.apache.org?
>
> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
> <a....@gmail.com> wrote:
>> 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 <a....@gmail.com>:
>>>
>>>> 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 <
>>>> a.budnikov.ignite@gmail.com>
>>>>> 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 <
>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>> 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 <
>>>>>>>> a.budnikov.ignite@gmail.com>
>>>>>>>>> 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
>>>>>>>>>>> <a.budnikov.ignite@gmail.com <ma...@gmail.com>>
>>>>>>>>>> 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
>>>>>>>>>>>          <a.budnikov.ignite@gmail.com <mailto:
>>>>>> a.budnikov.ignite@gmail.com
>>>>>>>>>>>          > 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,
>>>>>>>>>>>