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, 03 Aug 2020 09:55:08 GMT
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@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