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.ign...@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.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, > >>>>>>>>>
