ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Denis Magda <dma...@apache.org>
Subject Re: Moving Ignite documentation to github
Date Mon, 03 Aug 2020 14:55:00 GMT
I would wait for 3-4 weeks and release the new docs in 2.9. It means that
the release should be announced the first week of September which is not a
huge slip. Moreover, it feels like the testing phase and release procedures
will not be completed sooner.

So, I would suggest contributing 2.9 related page to the new documentation
repository.


Denis

On Monday, August 3, 2020, Artem Budnikov <a.budnikov.ignite@gmail.com>
wrote:

> Hi Maxim,
>
> The new docs project is not finished yet. There are still a lot of pages
> to port to the new format, and we are still working on the integration with
> the web-site. Nevertheless, we can try to publish the Ignite 2.9
> documentation on the web-site in the new format. The documentation will not
> be 100% complete, but it will be updated significantly and will contain
> most of the information our users need. Actually, I would like to do that,
> but it all depends on how much time I have before Ignite 2.9 is released.
> I'd say 2-3 weeks would be enough for me to finish all tasks that are
> critical for the publication.
>
> If we can wait with release 2.9 that much time, then I'll prepare the
> instruction on how to contribute to the docs.
>
> What do you think?
>
> -Artem
>
> On 03.08.2020 12:24, Maxim Muzafarov wrote:
>
>> Artem,
>>
>> I'd like to submit some documentation changes for 2.9 release. Should
>> I update docs on readme.io or publish it on ignite.apache.org?
>>
>> On Wed, 29 Jul 2020 at 19:06, Artem Budnikov
>> <a.budnikov.ignite@gmail.com> wrote:
>>
>>> Hi Alex,
>>>
>>> Sorry, I missed this message. There is still a lot of work on the docs.
>>> When is version 2.9 going to be released?
>>>
>>> -Artem
>>>
>>> On 22.07.2020 10:35, Alex Plehanov wrote:
>>>
>>>> Guys,
>>>>
>>>> What about documentation for 2.9 release? Are we going to publish it on
>>>> readme.io or publish it on ignite.apache.org?
>>>> What about new edits? Should we still edit pages on readme.io or
>>>> already
>>>> make changes in git repository?
>>>> Artem, could you please clarify the current documentation workflow?
>>>>
>>>>
>>>> пн, 20 июл. 2020 г. в 16:42, Artem Budnikov <
>>>> a.budnikov.ignite@gmail.com>:
>>>>
>>>> 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@gmai
>>>>>>>>>>>> l.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,
>>>>>>>>>>>>
>>>>>>>>>>>>

-- 
-
Denis

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message