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,
