+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 <[email protected]> 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 < > [email protected]> > > 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 > >>> <[email protected] <mailto:[email protected]>> > >> 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 > >>> <[email protected] <mailto:[email protected] > >> > >>> > 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, > >>> >
