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 Wed, 29 Jul 2020 16:06:27 GMT
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