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