ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Artem Budnikov <a.budnikov.ign...@gmail.com>
Subject Re: Moving Ignite documentation to github
Date Mon, 20 Jul 2020 11:41:52 GMT
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.ignite@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.ignite@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.ignite@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.ignite@gmail.com <mailto:a.budnikov.ignite@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.ignite@gmail.com <mailto:
>> a.budnikov.ignite@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,
>>>>>>>

Mime
View raw message