+1 to keep docs and sources together. -1 to keep docs in external repository.
> 23 июня 2020 г., в 16:47, Artem Budnikov <a.budnikov.ign...@gmail.com> > написал(а): > > 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, >>
