Alex,
The documentation source files are still in the IGNITE-7595 branch. I
haven't pushed them to the master yet, but I can do so if it is
necessary. Or, you can add your changes to this branch. I added an
instruction on how to contribute:
https://github.com/apache/ignite/blob/IGNITE-7595/docs/README.adoc
I suggest we do the first release of the new docs manually (just like we
do on readme.io) to get a sense of how the process works and how to
automate it better. Then, I'll document the entire process on our wiki.
Sounds good?
Artem
On 06.08.2020 11:37, Alex Plehanov wrote:
Denis, Artem,
I've marked the "tracing" ticket as important.
Also, I've added a new section to the release page [1] and created
documentation tickets for some features. Now there is a documentation
ticket exists for each important feature implemented in 2.9.
I know that some Igniters are currently working on documentation, but the
question is still unanswered: where to push changes? To GitHub, or to
readme.io? Guys, can you clarify, please?
[1]:
https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Documentationtasksforimportantfeaturesimplementedin2.9
вт, 4 авг. 2020 г. в 21:08, Denis Magda <dma...@apache.org>:
Hi Alex,
Certainly, the new documentation should not be treated as a showstopper,
and if the code is ready much earlier, then we can release the docs on
readme.io.
But, it's not clear what's the documentation readiness status. As per our
updated release process, the docs need to be ready before the voting is
started [1]. That change was discussed and introduced after our
lessons-learned conversations related to the 2.8 release.
Could you please help to figure out the status by preparing a list of
documentation tasks that must be completed before the voting time (all
significant features and changes)? The "most important tasks" section [2]
already lists most of them, but the list might be incomplete. For example,
the tracing feature should be added in 2.9, but it's not in the important
tasks list. There might be something else profound that we should put on
paper.
Once we get the list, we can start working with the contributors in charge
to get things done. If some documentation pages won't be finished in 2
weeks from now, then it's reasonable to contribute the 2.9 docs to the new
docs repository that will be ready for the release in 3-4 weeks. Just my
thinking.
[1]
https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
[2]
https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+2.9#ApacheIgnite2.9-Themostimportantreleasetasks
-
Denis
On Tue, Aug 4, 2020 at 5:54 AM Alex Plehanov <plehanov.a...@gmail.com>
wrote:
Denis,
We have some performance drop on benchmarks, so we need some time to find
problematic commit and analyze it. I hope this will be completed during
the
current week and we move to the "Vote preparation" phase to the start of
next week.
I think waiting for another month due to documentation it's too much.
Do we have an option to release with documentation on readme.io and then
move documentation in the new format during next month?
пн, 3 авг. 2020 г. в 17:55, Denis Magda <dma...@apache.org>:
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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@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.ign...@gmail.com <mailto:
a.budnikov.ign...@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
