ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Maxim Muzafarov <mmu...@apache.org>
Subject Re: Moving Ignite documentation to github
Date Mon, 03 Aug 2020 09:24:20 GMT
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