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.ign...@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.budnikov.ign...@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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@gmail.com <mailto: >>>>>>>>>>>> >>>>>>>>>>> a.budnikov.ign...@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
