You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Denis Magda <dm...@apache.org> on 2017/10/30 19:27:38 UTC
Let's keep Apache Ignite docs up-to-date
Igniters,
Our project is broadly documented so it’s becoming harder and harder to keep the docs consistent and updated. During several last months we tried the new approach with some of community members and took it down on paper:
https://cwiki.apache.org/confluence/display/IGNITE/Documentation
Please read it through and keep to it going forward or propose your changes if you’re like. Presently this approach proved to be effective.
—
Denis
Re: Let's keep Apache Ignite docs up-to-date
Posted by Anton Vinogradov <av...@gridgain.com>.
+1 to git case.
On Tue, Oct 31, 2017 at 12:35 PM, Pavel Tupitsyn <pt...@apache.org>
wrote:
> Hi Denis,
>
> Are there plans to move away from readme.io?
>
> * It is not properly versioned, which is very painful
> * Documentation should be in Apache git, not on some third party site
>
> Thoughts?
>
> On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org> wrote:
>
> > Good point. Renamed:
> > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
> > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
> >
> > —
> > Denis
> >
> > > On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> > wrote:
> > >
> > > Thanks Denis! Any change we can rename the page to "How to Document?".
> > >
> > > On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
> wrote:
> > >
> > >> Igniters,
> > >>
> > >> Our project is broadly documented so it’s becoming harder and harder
> to
> > >> keep the docs consistent and updated. During several last months we
> > tried
> > >> the new approach with some of community members and took it down on
> > paper:
> > >> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
> > >>
> > >> Please read it through and keep to it going forward or propose your
> > >> changes if you’re like. Presently this approach proved to be
> effective.
> > >>
> > >> —
> > >> Denis
> >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Denis Magda <dm...@apache.org>.
Pavel,
Could you show me any example of such a documentation where docs are stored in git and can be visualized by GitHub (dev stage) and 3rd party engine (release on the site)?
In my understanding if take your approach then the community needs to develop a visualization engine for ignite.apache.org <http://ignite.apache.org/>.
—
Denis
> On Oct 31, 2017, at 9:29 AM, Pavel Tupitsyn <pt...@apache.org> wrote:
>
>> easy to use editor
> Honestly, it sucks.
> I want to use my IDE and git instead of slow and buggy browser-based bs.
>
>> commit changes
> This is a good thing. I want to commit changes, see history, do other VCS
> stuff.
>
>> Github is also a third-party site
> I don't suggest github.
> We store code in Apache git [1], and we should store docs there as well,
> as most projects do.
>
> This way documentation can be developed, reviewed and merged with exactly
> the same process as used for code, which is great.
>
> ignite.apache.org should be used for hosting.
> Documentation release will be the same as source/binary/javadoc release:
> just push things to SVN.
>
>
> Thanks,
> Pavel
>
>
> [1] https://git-wip-us.apache.org/repos/asf/ignite
>
> On Tue, Oct 31, 2017 at 7:13 PM, Denis Magda <dm...@apache.org> wrote:
>
>> Hi Pavel,
>>
>> The lack of smooth versioning between pages on readme.io <
>> http://readme.io/> is redeemed with an easy to use editor. A doc writer
>> don’t need to grasp any markup language, commit changes to some remote repo
>> and check up final results. All the writer needs to do is to open a page
>> and update it seeing the changes immediately.
>>
>> Github is also a third-party site, so the docs won’t be hosted on ASF
>> infrastructure anyway.
>>
>> As a the one who prepares docs frequently, I can live with readme.io <
>> http://readme.io/>.
>>
>> —
>> Denis
>>
>>> On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org>
>> wrote:
>>>
>>> Hi Denis,
>>>
>>> Are there plans to move away from readme.io?
>>>
>>> * It is not properly versioned, which is very painful
>>> * Documentation should be in Apache git, not on some third party site
>>>
>>> Thoughts?
>>>
>>> On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org> wrote:
>>>
>>>> Good point. Renamed:
>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
>>>>
>>>> —
>>>> Denis
>>>>
>>>>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <dsetrakyan@apache.org
>>>
>>>> wrote:
>>>>>
>>>>> Thanks Denis! Any change we can rename the page to "How to Document?".
>>>>>
>>>>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
>> wrote:
>>>>>
>>>>>> Igniters,
>>>>>>
>>>>>> Our project is broadly documented so it’s becoming harder and harder
>> to
>>>>>> keep the docs consistent and updated. During several last months we
>>>> tried
>>>>>> the new approach with some of community members and took it down on
>>>> paper:
>>>>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
>>>>>>
>>>>>> Please read it through and keep to it going forward or propose your
>>>>>> changes if you’re like. Presently this approach proved to be
>> effective.
>>>>>>
>>>>>> —
>>>>>> Denis
>>>>
>>>>
>>
>>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Denis Magda <dm...@apache.org>.
Guys,
The migration process is in the progress. Here is a discussion where we
exchanged alternate doc engines (let's keep talking there):
http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
Add to the JIRA ticket as a watcher if you wish to track the progress:
https://issues.apache.org/jira/browse/IGNITE-7595
The goal is to migrate to the new docs by the next Ignite 2.5 release.
--
Denis
On Tue, Mar 6, 2018 at 2:43 AM, Guru Stron <gu...@gmail.com>
wrote:
> Hi, Igniters
>
> Missed this discussion
>
> +1 for git docs, as far as i can see this approach is used by many projects
> and it seems to be quite good.
>
>
> On 6 March 2018 at 11:44, Alexey Goncharuk <al...@gmail.com>
> wrote:
>
> > Igniters,
> >
> > Bumping up this discussion.
> >
> > I have recently found out that we have this process for documenting new
> > releases [1] which looks quite ridiculous to me.
> >
> > First, creating a copy of page with next-version suffix is inconvenient
> and
> > error-prone: the next-version page is not visible to anyone, moreover,
> all
> > suggested edits to current documentation will be lost after the page copy
> > is created. Second, the documentation changes should be transparent to
> > users, but now a regular user cannot even review upcoming changes until
> > they are granted a permission to see/edit hidden pages.
> >
> > Unless we have very strong reasons to keep documentation on readme.io
> (by
> > strong I mean a feature that cannot be implemented using a VCS + doc
> > generator), I would at least spend some time piloting the 'keep docs in
> the
> > VCS' approach.
> >
> > Thoughts?
> >
> > [1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document
> >
> > 2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <dp...@gmail.com>:
> >
> > > I don't like git docs idea, it will require to follow whole
> > > PR-review-process that requires long time. IMO it is odd work.
> > > If readme.io provides review process, I suggest to keep it as-is.
> > >
> > > чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <ds...@apache.org>:
> > >
> > > > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <
> vozerov@gridgain.com
> > >
> > > > wrote:
> > > >
> > > > > +1 for moving docs under Git provided that we find a way to update
> > docs
> > > > > outside of AI release as it is possible now with readme.io.
> > > > >
> > > >
> > > > I am HUGE +1 for that. The whole problem is that we haven't found a
> way
> > > > yet. All I want is to update a page and have it commit to GIT and
> > become
> > > > available to public right away. Does anyone know any tool that
> supports
> > > it?
> > > >
> > >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Guru Stron <gu...@gmail.com>.
Hi, Igniters
Missed this discussion
+1 for git docs, as far as i can see this approach is used by many projects
and it seems to be quite good.
On 6 March 2018 at 11:44, Alexey Goncharuk <al...@gmail.com>
wrote:
> Igniters,
>
> Bumping up this discussion.
>
> I have recently found out that we have this process for documenting new
> releases [1] which looks quite ridiculous to me.
>
> First, creating a copy of page with next-version suffix is inconvenient and
> error-prone: the next-version page is not visible to anyone, moreover, all
> suggested edits to current documentation will be lost after the page copy
> is created. Second, the documentation changes should be transparent to
> users, but now a regular user cannot even review upcoming changes until
> they are granted a permission to see/edit hidden pages.
>
> Unless we have very strong reasons to keep documentation on readme.io (by
> strong I mean a feature that cannot be implemented using a VCS + doc
> generator), I would at least spend some time piloting the 'keep docs in the
> VCS' approach.
>
> Thoughts?
>
> [1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document
>
> 2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <dp...@gmail.com>:
>
> > I don't like git docs idea, it will require to follow whole
> > PR-review-process that requires long time. IMO it is odd work.
> > If readme.io provides review process, I suggest to keep it as-is.
> >
> > чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <ds...@apache.org>:
> >
> > > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <vozerov@gridgain.com
> >
> > > wrote:
> > >
> > > > +1 for moving docs under Git provided that we find a way to update
> docs
> > > > outside of AI release as it is possible now with readme.io.
> > > >
> > >
> > > I am HUGE +1 for that. The whole problem is that we haven't found a way
> > > yet. All I want is to update a page and have it commit to GIT and
> become
> > > available to public right away. Does anyone know any tool that supports
> > it?
> > >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Alexey Goncharuk <al...@gmail.com>.
Igniters,
Bumping up this discussion.
I have recently found out that we have this process for documenting new
releases [1] which looks quite ridiculous to me.
First, creating a copy of page with next-version suffix is inconvenient and
error-prone: the next-version page is not visible to anyone, moreover, all
suggested edits to current documentation will be lost after the page copy
is created. Second, the documentation changes should be transparent to
users, but now a regular user cannot even review upcoming changes until
they are granted a permission to see/edit hidden pages.
Unless we have very strong reasons to keep documentation on readme.io (by
strong I mean a feature that cannot be implemented using a VCS + doc
generator), I would at least spend some time piloting the 'keep docs in the
VCS' approach.
Thoughts?
[1] https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document
2017-11-02 10:07 GMT+03:00 Dmitry Pavlov <dp...@gmail.com>:
> I don't like git docs idea, it will require to follow whole
> PR-review-process that requires long time. IMO it is odd work.
> If readme.io provides review process, I suggest to keep it as-is.
>
> чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <ds...@apache.org>:
>
> > On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <vo...@gridgain.com>
> > wrote:
> >
> > > +1 for moving docs under Git provided that we find a way to update docs
> > > outside of AI release as it is possible now with readme.io.
> > >
> >
> > I am HUGE +1 for that. The whole problem is that we haven't found a way
> > yet. All I want is to update a page and have it commit to GIT and become
> > available to public right away. Does anyone know any tool that supports
> it?
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitry Pavlov <dp...@gmail.com>.
I don't like git docs idea, it will require to follow whole
PR-review-process that requires long time. IMO it is odd work.
If readme.io provides review process, I suggest to keep it as-is.
чт, 2 нояб. 2017 г. в 9:57, Dmitriy Setrakyan <ds...@apache.org>:
> On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <vo...@gridgain.com>
> wrote:
>
> > +1 for moving docs under Git provided that we find a way to update docs
> > outside of AI release as it is possible now with readme.io.
> >
>
> I am HUGE +1 for that. The whole problem is that we haven't found a way
> yet. All I want is to update a page and have it commit to GIT and become
> available to public right away. Does anyone know any tool that supports it?
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Wed, Nov 1, 2017 at 11:27 PM, Vladimir Ozerov <vo...@gridgain.com>
wrote:
> +1 for moving docs under Git provided that we find a way to update docs
> outside of AI release as it is possible now with readme.io.
>
I am HUGE +1 for that. The whole problem is that we haven't found a way
yet. All I want is to update a page and have it commit to GIT and become
available to public right away. Does anyone know any tool that supports it?
Re: Let's keep Apache Ignite docs up-to-date
Posted by Vladimir Ozerov <vo...@gridgain.com>.
+1 for moving docs under Git provided that we find a way to update docs
outside of AI release as it is possible now with readme.io.
On Thu, Nov 2, 2017 at 8:57 AM, Pavel Tupitsyn <pt...@apache.org> wrote:
> > I can edit a document and it is visible to the whole world once I click a
> save button
> I see this as a huge downside.
> Anyone can screw up entire documentation with a single misplaced click,
> and you can't even see the history or have an ability to restore the
> previous version.
>
> Right now I can go and remove any page, and you would not even know who did
> that.
> (or am I missing something? can you revert and restore things?)
>
>
> On Thu, Nov 2, 2017 at 2:35 AM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
>
> > I am going to repeat my previous comment, since it somehow got lost in
> the
> > discussion:
> >
> > The main value of readme is that I can edit a document and it is visible
> to
> > the whole world once I click a save button, without any git commands or
> > builds. If anyone in the community can suggest a tool that will work the
> > same way with Apache git repository directly, please send it here.
> >
> > D.
> >
> > On Wed, Nov 1, 2017 at 4:26 AM, Anton Vinogradov <
> avinogradov@gridgain.com
> > >
> > wrote:
> >
> > > +1 to Pavel's proposal,
> > >
> > > > Markdown can also be visualized by many IDEs, so it is easy to edit
> > > locally.
> > > IDEA shows Markdown out of the box.
> > >
> > > Yakov,
> > >
> > > > having docs under separate git repository
> > > We should not use separate git repo, Apache Ignite repo should be used.
> > > Documentation should be a part of pull request.
> > >
> > > On Wed, Nov 1, 2017 at 10:08 AM, Pavel Tupitsyn <pt...@apache.org>
> > > wrote:
> > >
> > > > Denis,
> > > >
> > > > > Could you show me any example of such a documentation where docs
> are
> > > > stored in git and can be visualized by GitHub (dev stage) and 3rd
> party
> > > > engine (release on the site)?
> > > >
> > > > 1) Apache Spark
> > > > Source: https://github.com/apache/spark/tree/master/docs
> > > > Docs: https://spark.apache.org/documentation.html
> > > > (uses Jekyll)
> > > >
> > > > 2) Microsoft .NET
> > > > Source: https://github.com/dotnet/docs
> > > > Docs: https://docs.microsoft.com/en-us/dotnet/
> > > > (uses DocFX)
> > > >
> > > >
> > > > Both of these engines (Jekyll and DocFX) use markdown, which can be
> > > > visualized by github, and converted to HTML for the web site.
> > > > Markdown can also be visualized by many IDEs, so it is easy to edit
> > > > locally.
> > > >
> > > > Ideally, API docs (javadoc) should be integrated with the rest of the
> > > docs,
> > > > so users can navigate to the corresponding APIs.
> > > > This can't be achieved nicely with readme.io.
> > > >
> > > >
> > > > > having docs under separate git repository
> > > > I don't think we need a separate repo, we can just create branches in
> > our
> > > > main repo for that.
> > > > It is nice to have everything in one place.
> > > >
> > > > On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <
> > dsetrakyan@apache.org
> > > >
> > > > wrote:
> > > >
> > > > > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <
> yzhdanov@apache.org>
> > > > > wrote:
> > > > >
> > > > > > I would also consider having docs under separate git repository.
> > > > Separate
> > > > > > since we need to have an opportunity to revisit documentation for
> > > > already
> > > > > > released versions.
> > > > > >
> > > > >
> > > > > This should not be a problem.
> > > > >
> > > >
> > >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Pavel Tupitsyn <pt...@apache.org>.
> I can edit a document and it is visible to the whole world once I click a
save button
I see this as a huge downside.
Anyone can screw up entire documentation with a single misplaced click,
and you can't even see the history or have an ability to restore the
previous version.
Right now I can go and remove any page, and you would not even know who did
that.
(or am I missing something? can you revert and restore things?)
On Thu, Nov 2, 2017 at 2:35 AM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> I am going to repeat my previous comment, since it somehow got lost in the
> discussion:
>
> The main value of readme is that I can edit a document and it is visible to
> the whole world once I click a save button, without any git commands or
> builds. If anyone in the community can suggest a tool that will work the
> same way with Apache git repository directly, please send it here.
>
> D.
>
> On Wed, Nov 1, 2017 at 4:26 AM, Anton Vinogradov <avinogradov@gridgain.com
> >
> wrote:
>
> > +1 to Pavel's proposal,
> >
> > > Markdown can also be visualized by many IDEs, so it is easy to edit
> > locally.
> > IDEA shows Markdown out of the box.
> >
> > Yakov,
> >
> > > having docs under separate git repository
> > We should not use separate git repo, Apache Ignite repo should be used.
> > Documentation should be a part of pull request.
> >
> > On Wed, Nov 1, 2017 at 10:08 AM, Pavel Tupitsyn <pt...@apache.org>
> > wrote:
> >
> > > Denis,
> > >
> > > > Could you show me any example of such a documentation where docs are
> > > stored in git and can be visualized by GitHub (dev stage) and 3rd party
> > > engine (release on the site)?
> > >
> > > 1) Apache Spark
> > > Source: https://github.com/apache/spark/tree/master/docs
> > > Docs: https://spark.apache.org/documentation.html
> > > (uses Jekyll)
> > >
> > > 2) Microsoft .NET
> > > Source: https://github.com/dotnet/docs
> > > Docs: https://docs.microsoft.com/en-us/dotnet/
> > > (uses DocFX)
> > >
> > >
> > > Both of these engines (Jekyll and DocFX) use markdown, which can be
> > > visualized by github, and converted to HTML for the web site.
> > > Markdown can also be visualized by many IDEs, so it is easy to edit
> > > locally.
> > >
> > > Ideally, API docs (javadoc) should be integrated with the rest of the
> > docs,
> > > so users can navigate to the corresponding APIs.
> > > This can't be achieved nicely with readme.io.
> > >
> > >
> > > > having docs under separate git repository
> > > I don't think we need a separate repo, we can just create branches in
> our
> > > main repo for that.
> > > It is nice to have everything in one place.
> > >
> > > On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <
> dsetrakyan@apache.org
> > >
> > > wrote:
> > >
> > > > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yz...@apache.org>
> > > > wrote:
> > > >
> > > > > I would also consider having docs under separate git repository.
> > > Separate
> > > > > since we need to have an opportunity to revisit documentation for
> > > already
> > > > > released versions.
> > > > >
> > > >
> > > > This should not be a problem.
> > > >
> > >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitriy Setrakyan <ds...@apache.org>.
I am going to repeat my previous comment, since it somehow got lost in the
discussion:
The main value of readme is that I can edit a document and it is visible to
the whole world once I click a save button, without any git commands or
builds. If anyone in the community can suggest a tool that will work the
same way with Apache git repository directly, please send it here.
D.
On Wed, Nov 1, 2017 at 4:26 AM, Anton Vinogradov <av...@gridgain.com>
wrote:
> +1 to Pavel's proposal,
>
> > Markdown can also be visualized by many IDEs, so it is easy to edit
> locally.
> IDEA shows Markdown out of the box.
>
> Yakov,
>
> > having docs under separate git repository
> We should not use separate git repo, Apache Ignite repo should be used.
> Documentation should be a part of pull request.
>
> On Wed, Nov 1, 2017 at 10:08 AM, Pavel Tupitsyn <pt...@apache.org>
> wrote:
>
> > Denis,
> >
> > > Could you show me any example of such a documentation where docs are
> > stored in git and can be visualized by GitHub (dev stage) and 3rd party
> > engine (release on the site)?
> >
> > 1) Apache Spark
> > Source: https://github.com/apache/spark/tree/master/docs
> > Docs: https://spark.apache.org/documentation.html
> > (uses Jekyll)
> >
> > 2) Microsoft .NET
> > Source: https://github.com/dotnet/docs
> > Docs: https://docs.microsoft.com/en-us/dotnet/
> > (uses DocFX)
> >
> >
> > Both of these engines (Jekyll and DocFX) use markdown, which can be
> > visualized by github, and converted to HTML for the web site.
> > Markdown can also be visualized by many IDEs, so it is easy to edit
> > locally.
> >
> > Ideally, API docs (javadoc) should be integrated with the rest of the
> docs,
> > so users can navigate to the corresponding APIs.
> > This can't be achieved nicely with readme.io.
> >
> >
> > > having docs under separate git repository
> > I don't think we need a separate repo, we can just create branches in our
> > main repo for that.
> > It is nice to have everything in one place.
> >
> > On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> > wrote:
> >
> > > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yz...@apache.org>
> > > wrote:
> > >
> > > > I would also consider having docs under separate git repository.
> > Separate
> > > > since we need to have an opportunity to revisit documentation for
> > already
> > > > released versions.
> > > >
> > >
> > > This should not be a problem.
> > >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Anton Vinogradov <av...@gridgain.com>.
+1 to Pavel's proposal,
> Markdown can also be visualized by many IDEs, so it is easy to edit
locally.
IDEA shows Markdown out of the box.
Yakov,
> having docs under separate git repository
We should not use separate git repo, Apache Ignite repo should be used.
Documentation should be a part of pull request.
On Wed, Nov 1, 2017 at 10:08 AM, Pavel Tupitsyn <pt...@apache.org>
wrote:
> Denis,
>
> > Could you show me any example of such a documentation where docs are
> stored in git and can be visualized by GitHub (dev stage) and 3rd party
> engine (release on the site)?
>
> 1) Apache Spark
> Source: https://github.com/apache/spark/tree/master/docs
> Docs: https://spark.apache.org/documentation.html
> (uses Jekyll)
>
> 2) Microsoft .NET
> Source: https://github.com/dotnet/docs
> Docs: https://docs.microsoft.com/en-us/dotnet/
> (uses DocFX)
>
>
> Both of these engines (Jekyll and DocFX) use markdown, which can be
> visualized by github, and converted to HTML for the web site.
> Markdown can also be visualized by many IDEs, so it is easy to edit
> locally.
>
> Ideally, API docs (javadoc) should be integrated with the rest of the docs,
> so users can navigate to the corresponding APIs.
> This can't be achieved nicely with readme.io.
>
>
> > having docs under separate git repository
> I don't think we need a separate repo, we can just create branches in our
> main repo for that.
> It is nice to have everything in one place.
>
> On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
>
> > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yz...@apache.org>
> > wrote:
> >
> > > I would also consider having docs under separate git repository.
> Separate
> > > since we need to have an opportunity to revisit documentation for
> already
> > > released versions.
> > >
> >
> > This should not be a problem.
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Pavel Tupitsyn <pt...@apache.org>.
Denis,
> Could you show me any example of such a documentation where docs are
stored in git and can be visualized by GitHub (dev stage) and 3rd party
engine (release on the site)?
1) Apache Spark
Source: https://github.com/apache/spark/tree/master/docs
Docs: https://spark.apache.org/documentation.html
(uses Jekyll)
2) Microsoft .NET
Source: https://github.com/dotnet/docs
Docs: https://docs.microsoft.com/en-us/dotnet/
(uses DocFX)
Both of these engines (Jekyll and DocFX) use markdown, which can be
visualized by github, and converted to HTML for the web site.
Markdown can also be visualized by many IDEs, so it is easy to edit locally.
Ideally, API docs (javadoc) should be integrated with the rest of the docs,
so users can navigate to the corresponding APIs.
This can't be achieved nicely with readme.io.
> having docs under separate git repository
I don't think we need a separate repo, we can just create branches in our
main repo for that.
It is nice to have everything in one place.
On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yz...@apache.org>
> wrote:
>
> > I would also consider having docs under separate git repository. Separate
> > since we need to have an opportunity to revisit documentation for already
> > released versions.
> >
>
> This should not be a problem.
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yz...@apache.org> wrote:
> I would also consider having docs under separate git repository. Separate
> since we need to have an opportunity to revisit documentation for already
> released versions.
>
This should not be a problem.
Re: Let's keep Apache Ignite docs up-to-date
Posted by Yakov Zhdanov <yz...@apache.org>.
I would also consider having docs under separate git repository. Separate
since we need to have an opportunity to revisit documentation for already
released versions.
--Yakov
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitriy Setrakyan <ds...@apache.org>.
The main value of readme is that I can edit a document and it is visible to
the whole world once I click a save button, without any git commands or
builds. If anyone in the community can suggest a tool that will work the
same way with Apache git repository directly, please send it here.
D.
On Tue, Oct 31, 2017 at 10:56 AM, Denis Magda <dm...@apache.org> wrote:
> Anton,
>
> The life is not about coding only :)
>
> Sometimes we need to learn new tools to produce nice looking, well
> organized and professional content. Take Photopshop or Mac Keynote for
> instance that help us out with diagrams and presentations creation.
> Readme.io <http://readme.io/> does it job well as a tool for technical
> writers.
>
> —
> Denis
>
> > On Oct 31, 2017, at 9:47 AM, Anton Vinogradov <av...@apache.org> wrote:
> >
> > Simplified:
> > Current flow is over-complicated for me as developer, I see a lot of
> > problems and have no clue how to fix them using readme.io or wiki.
> > But I know how to fix them using git.
> > I'm good at git, let me write documentation in way I'm good in :)
> >
> >
> > On Tue, Oct 31, 2017 at 7:29 PM, Pavel Tupitsyn <pt...@apache.org>
> > wrote:
> >
> >>> easy to use editor
> >> Honestly, it sucks.
> >> I want to use my IDE and git instead of slow and buggy browser-based bs.
> >>
> >>> commit changes
> >> This is a good thing. I want to commit changes, see history, do other
> VCS
> >> stuff.
> >>
> >>> Github is also a third-party site
> >> I don't suggest github.
> >> We store code in Apache git [1], and we should store docs there as well,
> >> as most projects do.
> >>
> >> This way documentation can be developed, reviewed and merged with
> exactly
> >> the same process as used for code, which is great.
> >>
> >> ignite.apache.org should be used for hosting.
> >> Documentation release will be the same as source/binary/javadoc release:
> >> just push things to SVN.
> >>
> >>
> >> Thanks,
> >> Pavel
> >>
> >>
> >> [1] https://git-wip-us.apache.org/repos/asf/ignite
> >>
> >> On Tue, Oct 31, 2017 at 7:13 PM, Denis Magda <dm...@apache.org> wrote:
> >>
> >>> Hi Pavel,
> >>>
> >>> The lack of smooth versioning between pages on readme.io <
> >>> http://readme.io/> is redeemed with an easy to use editor. A doc
> writer
> >>> don’t need to grasp any markup language, commit changes to some remote
> >> repo
> >>> and check up final results. All the writer needs to do is to open a
> page
> >>> and update it seeing the changes immediately.
> >>>
> >>> Github is also a third-party site, so the docs won’t be hosted on ASF
> >>> infrastructure anyway.
> >>>
> >>> As a the one who prepares docs frequently, I can live with readme.io <
> >>> http://readme.io/>.
> >>>
> >>> —
> >>> Denis
> >>>
> >>>> On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org>
> >>> wrote:
> >>>>
> >>>> Hi Denis,
> >>>>
> >>>> Are there plans to move away from readme.io?
> >>>>
> >>>> * It is not properly versioned, which is very painful
> >>>> * Documentation should be in Apache git, not on some third party site
> >>>>
> >>>> Thoughts?
> >>>>
> >>>> On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org>
> >> wrote:
> >>>>
> >>>>> Good point. Renamed:
> >>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
> >>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
> >>>>>
> >>>>> —
> >>>>> Denis
> >>>>>
> >>>>>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <
> >> dsetrakyan@apache.org
> >>>>
> >>>>> wrote:
> >>>>>>
> >>>>>> Thanks Denis! Any change we can rename the page to "How to
> >> Document?".
> >>>>>>
> >>>>>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
> >>> wrote:
> >>>>>>
> >>>>>>> Igniters,
> >>>>>>>
> >>>>>>> Our project is broadly documented so it’s becoming harder and
> harder
> >>> to
> >>>>>>> keep the docs consistent and updated. During several last months we
> >>>>> tried
> >>>>>>> the new approach with some of community members and took it down on
> >>>>> paper:
> >>>>>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
> >>>>>>>
> >>>>>>> Please read it through and keep to it going forward or propose your
> >>>>>>> changes if you’re like. Presently this approach proved to be
> >>> effective.
> >>>>>>>
> >>>>>>> —
> >>>>>>> Denis
> >>>>>
> >>>>>
> >>>
> >>>
> >>
>
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Denis Magda <dm...@apache.org>.
Anton,
The life is not about coding only :)
Sometimes we need to learn new tools to produce nice looking, well organized and professional content. Take Photopshop or Mac Keynote for instance that help us out with diagrams and presentations creation. Readme.io <http://readme.io/> does it job well as a tool for technical writers.
—
Denis
> On Oct 31, 2017, at 9:47 AM, Anton Vinogradov <av...@apache.org> wrote:
>
> Simplified:
> Current flow is over-complicated for me as developer, I see a lot of
> problems and have no clue how to fix them using readme.io or wiki.
> But I know how to fix them using git.
> I'm good at git, let me write documentation in way I'm good in :)
>
>
> On Tue, Oct 31, 2017 at 7:29 PM, Pavel Tupitsyn <pt...@apache.org>
> wrote:
>
>>> easy to use editor
>> Honestly, it sucks.
>> I want to use my IDE and git instead of slow and buggy browser-based bs.
>>
>>> commit changes
>> This is a good thing. I want to commit changes, see history, do other VCS
>> stuff.
>>
>>> Github is also a third-party site
>> I don't suggest github.
>> We store code in Apache git [1], and we should store docs there as well,
>> as most projects do.
>>
>> This way documentation can be developed, reviewed and merged with exactly
>> the same process as used for code, which is great.
>>
>> ignite.apache.org should be used for hosting.
>> Documentation release will be the same as source/binary/javadoc release:
>> just push things to SVN.
>>
>>
>> Thanks,
>> Pavel
>>
>>
>> [1] https://git-wip-us.apache.org/repos/asf/ignite
>>
>> On Tue, Oct 31, 2017 at 7:13 PM, Denis Magda <dm...@apache.org> wrote:
>>
>>> Hi Pavel,
>>>
>>> The lack of smooth versioning between pages on readme.io <
>>> http://readme.io/> is redeemed with an easy to use editor. A doc writer
>>> don’t need to grasp any markup language, commit changes to some remote
>> repo
>>> and check up final results. All the writer needs to do is to open a page
>>> and update it seeing the changes immediately.
>>>
>>> Github is also a third-party site, so the docs won’t be hosted on ASF
>>> infrastructure anyway.
>>>
>>> As a the one who prepares docs frequently, I can live with readme.io <
>>> http://readme.io/>.
>>>
>>> —
>>> Denis
>>>
>>>> On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org>
>>> wrote:
>>>>
>>>> Hi Denis,
>>>>
>>>> Are there plans to move away from readme.io?
>>>>
>>>> * It is not properly versioned, which is very painful
>>>> * Documentation should be in Apache git, not on some third party site
>>>>
>>>> Thoughts?
>>>>
>>>> On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org>
>> wrote:
>>>>
>>>>> Good point. Renamed:
>>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
>>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
>>>>>
>>>>> —
>>>>> Denis
>>>>>
>>>>>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <
>> dsetrakyan@apache.org
>>>>
>>>>> wrote:
>>>>>>
>>>>>> Thanks Denis! Any change we can rename the page to "How to
>> Document?".
>>>>>>
>>>>>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
>>> wrote:
>>>>>>
>>>>>>> Igniters,
>>>>>>>
>>>>>>> Our project is broadly documented so it’s becoming harder and harder
>>> to
>>>>>>> keep the docs consistent and updated. During several last months we
>>>>> tried
>>>>>>> the new approach with some of community members and took it down on
>>>>> paper:
>>>>>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
>>>>>>>
>>>>>>> Please read it through and keep to it going forward or propose your
>>>>>>> changes if you’re like. Presently this approach proved to be
>>> effective.
>>>>>>>
>>>>>>> —
>>>>>>> Denis
>>>>>
>>>>>
>>>
>>>
>>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Anton Vinogradov <av...@apache.org>.
Simplified:
Current flow is over-complicated for me as developer, I see a lot of
problems and have no clue how to fix them using readme.io or wiki.
But I know how to fix them using git.
I'm good at git, let me write documentation in way I'm good in :)
On Tue, Oct 31, 2017 at 7:29 PM, Pavel Tupitsyn <pt...@apache.org>
wrote:
> > easy to use editor
> Honestly, it sucks.
> I want to use my IDE and git instead of slow and buggy browser-based bs.
>
> > commit changes
> This is a good thing. I want to commit changes, see history, do other VCS
> stuff.
>
> > Github is also a third-party site
> I don't suggest github.
> We store code in Apache git [1], and we should store docs there as well,
> as most projects do.
>
> This way documentation can be developed, reviewed and merged with exactly
> the same process as used for code, which is great.
>
> ignite.apache.org should be used for hosting.
> Documentation release will be the same as source/binary/javadoc release:
> just push things to SVN.
>
>
> Thanks,
> Pavel
>
>
> [1] https://git-wip-us.apache.org/repos/asf/ignite
>
> On Tue, Oct 31, 2017 at 7:13 PM, Denis Magda <dm...@apache.org> wrote:
>
> > Hi Pavel,
> >
> > The lack of smooth versioning between pages on readme.io <
> > http://readme.io/> is redeemed with an easy to use editor. A doc writer
> > don’t need to grasp any markup language, commit changes to some remote
> repo
> > and check up final results. All the writer needs to do is to open a page
> > and update it seeing the changes immediately.
> >
> > Github is also a third-party site, so the docs won’t be hosted on ASF
> > infrastructure anyway.
> >
> > As a the one who prepares docs frequently, I can live with readme.io <
> > http://readme.io/>.
> >
> > —
> > Denis
> >
> > > On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org>
> > wrote:
> > >
> > > Hi Denis,
> > >
> > > Are there plans to move away from readme.io?
> > >
> > > * It is not properly versioned, which is very painful
> > > * Documentation should be in Apache git, not on some third party site
> > >
> > > Thoughts?
> > >
> > > On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org>
> wrote:
> > >
> > >> Good point. Renamed:
> > >> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
> > >> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
> > >>
> > >> —
> > >> Denis
> > >>
> > >>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <
> dsetrakyan@apache.org
> > >
> > >> wrote:
> > >>>
> > >>> Thanks Denis! Any change we can rename the page to "How to
> Document?".
> > >>>
> > >>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
> > wrote:
> > >>>
> > >>>> Igniters,
> > >>>>
> > >>>> Our project is broadly documented so it’s becoming harder and harder
> > to
> > >>>> keep the docs consistent and updated. During several last months we
> > >> tried
> > >>>> the new approach with some of community members and took it down on
> > >> paper:
> > >>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
> > >>>>
> > >>>> Please read it through and keep to it going forward or propose your
> > >>>> changes if you’re like. Presently this approach proved to be
> > effective.
> > >>>>
> > >>>> —
> > >>>> Denis
> > >>
> > >>
> >
> >
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Pavel Tupitsyn <pt...@apache.org>.
> easy to use editor
Honestly, it sucks.
I want to use my IDE and git instead of slow and buggy browser-based bs.
> commit changes
This is a good thing. I want to commit changes, see history, do other VCS
stuff.
> Github is also a third-party site
I don't suggest github.
We store code in Apache git [1], and we should store docs there as well,
as most projects do.
This way documentation can be developed, reviewed and merged with exactly
the same process as used for code, which is great.
ignite.apache.org should be used for hosting.
Documentation release will be the same as source/binary/javadoc release:
just push things to SVN.
Thanks,
Pavel
[1] https://git-wip-us.apache.org/repos/asf/ignite
On Tue, Oct 31, 2017 at 7:13 PM, Denis Magda <dm...@apache.org> wrote:
> Hi Pavel,
>
> The lack of smooth versioning between pages on readme.io <
> http://readme.io/> is redeemed with an easy to use editor. A doc writer
> don’t need to grasp any markup language, commit changes to some remote repo
> and check up final results. All the writer needs to do is to open a page
> and update it seeing the changes immediately.
>
> Github is also a third-party site, so the docs won’t be hosted on ASF
> infrastructure anyway.
>
> As a the one who prepares docs frequently, I can live with readme.io <
> http://readme.io/>.
>
> —
> Denis
>
> > On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org>
> wrote:
> >
> > Hi Denis,
> >
> > Are there plans to move away from readme.io?
> >
> > * It is not properly versioned, which is very painful
> > * Documentation should be in Apache git, not on some third party site
> >
> > Thoughts?
> >
> > On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org> wrote:
> >
> >> Good point. Renamed:
> >> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
> >> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
> >>
> >> —
> >> Denis
> >>
> >>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> >> wrote:
> >>>
> >>> Thanks Denis! Any change we can rename the page to "How to Document?".
> >>>
> >>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org>
> wrote:
> >>>
> >>>> Igniters,
> >>>>
> >>>> Our project is broadly documented so it’s becoming harder and harder
> to
> >>>> keep the docs consistent and updated. During several last months we
> >> tried
> >>>> the new approach with some of community members and took it down on
> >> paper:
> >>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
> >>>>
> >>>> Please read it through and keep to it going forward or propose your
> >>>> changes if you’re like. Presently this approach proved to be
> effective.
> >>>>
> >>>> —
> >>>> Denis
> >>
> >>
>
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Denis Magda <dm...@apache.org>.
Hi Pavel,
The lack of smooth versioning between pages on readme.io <http://readme.io/> is redeemed with an easy to use editor. A doc writer don’t need to grasp any markup language, commit changes to some remote repo and check up final results. All the writer needs to do is to open a page and update it seeing the changes immediately.
Github is also a third-party site, so the docs won’t be hosted on ASF infrastructure anyway.
As a the one who prepares docs frequently, I can live with readme.io <http://readme.io/>.
—
Denis
> On Oct 31, 2017, at 2:35 AM, Pavel Tupitsyn <pt...@apache.org> wrote:
>
> Hi Denis,
>
> Are there plans to move away from readme.io?
>
> * It is not properly versioned, which is very painful
> * Documentation should be in Apache git, not on some third party site
>
> Thoughts?
>
> On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org> wrote:
>
>> Good point. Renamed:
>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
>> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
>>
>> —
>> Denis
>>
>>> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <ds...@apache.org>
>> wrote:
>>>
>>> Thanks Denis! Any change we can rename the page to "How to Document?".
>>>
>>> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org> wrote:
>>>
>>>> Igniters,
>>>>
>>>> Our project is broadly documented so it’s becoming harder and harder to
>>>> keep the docs consistent and updated. During several last months we
>> tried
>>>> the new approach with some of community members and took it down on
>> paper:
>>>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
>>>>
>>>> Please read it through and keep to it going forward or propose your
>>>> changes if you’re like. Presently this approach proved to be effective.
>>>>
>>>> —
>>>> Denis
>>
>>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Pavel Tupitsyn <pt...@apache.org>.
Hi Denis,
Are there plans to move away from readme.io?
* It is not properly versioned, which is very painful
* Documentation should be in Apache git, not on some third party site
Thoughts?
On Mon, Oct 30, 2017 at 11:24 PM, Denis Magda <dm...@apache.org> wrote:
> Good point. Renamed:
> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <
> https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
>
> —
> Denis
>
> > On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
> >
> > Thanks Denis! Any change we can rename the page to "How to Document?".
> >
> > On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org> wrote:
> >
> >> Igniters,
> >>
> >> Our project is broadly documented so it’s becoming harder and harder to
> >> keep the docs consistent and updated. During several last months we
> tried
> >> the new approach with some of community members and took it down on
> paper:
> >> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
> >>
> >> Please read it through and keep to it going forward or propose your
> >> changes if you’re like. Presently this approach proved to be effective.
> >>
> >> —
> >> Denis
>
>
Re: Let's keep Apache Ignite docs up-to-date
Posted by Denis Magda <dm...@apache.org>.
Good point. Renamed:
https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document <https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document>
—
Denis
> On Oct 30, 2017, at 12:37 PM, Dmitriy Setrakyan <ds...@apache.org> wrote:
>
> Thanks Denis! Any change we can rename the page to "How to Document?".
>
> On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org> wrote:
>
>> Igniters,
>>
>> Our project is broadly documented so it’s becoming harder and harder to
>> keep the docs consistent and updated. During several last months we tried
>> the new approach with some of community members and took it down on paper:
>> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
>>
>> Please read it through and keep to it going forward or propose your
>> changes if you’re like. Presently this approach proved to be effective.
>>
>> —
>> Denis
Re: Let's keep Apache Ignite docs up-to-date
Posted by Dmitriy Setrakyan <ds...@apache.org>.
Thanks Denis! Any change we can rename the page to "How to Document?".
On Mon, Oct 30, 2017 at 12:27 PM, Denis Magda <dm...@apache.org> wrote:
> Igniters,
>
> Our project is broadly documented so it’s becoming harder and harder to
> keep the docs consistent and updated. During several last months we tried
> the new approach with some of community members and took it down on paper:
> https://cwiki.apache.org/confluence/display/IGNITE/Documentation
>
> Please read it through and keep to it going forward or propose your
> changes if you’re like. Presently this approach proved to be effective.
>
> —
> Denis