Move documentation from readme.io to GitHub pages

[Pavel Tupitsyn]

Igniters,

Currently we host documentation on
apacheignite.readme.io (and also apacheignite-net.readme.io,
apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).

readme.io has a lot of problems mostly due to lack of proper version
control:
* Each "version" is just a copy. When fixing something, you have to update
all versions.
* No good way to review changes.
* "Propose edit" functionality is a joke. You can only accept or reject an
edit, no way to communicate with contributor, etc

GitHub Pages solves all these problems:
https://github.com/blog/2233-publish-your-project-documentation-with-github-pages

Basically, we'll have a separate folder in our Git repository where
documentation is stored in markdown format.
This way the process for updating docs is exactly the same as any other
code change.
Pull request with new feature can contain the docs for this feature, and so
on.

Thoughts?

[Igor Sapego-2]

Pavel,

I totally agree with you, but what about documentations for different
versions? How do you suppose to solve this problem with GitHub pages?

On Tue, Apr 11, 2017 at 12:02 PM, Pavel Tupitsyn <[hidden email]>
wrote:

> Igniters,
>
> Currently we host documentation on
> apacheignite.readme.io (and also apacheignite-net.readme.io,
> apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).
>
> readme.io has a lot of problems mostly due to lack of proper version
> control:
> * Each "version" is just a copy. When fixing something, you have to update
> all versions.
> * No good way to review changes.
> * "Propose edit" functionality is a joke. You can only accept or reject an
> edit, no way to communicate with contributor, etc
>
> GitHub Pages solves all these problems:
> https://github.com/blog/2233-publish-your-project-
> documentation-with-github-pages
>
> Basically, we'll have a separate folder in our Git repository where
> documentation is stored in markdown format.
> This way the process for updating docs is exactly the same as any other
> code change.
> Pull request with new feature can contain the docs for this feature, and so
> on.
>
> Thoughts?
>

[dmagda]

Pavel,

I totally agree that it’s becoming more and more inconvenient to run the documentation on readme.io <http://readme.io/>. At the same time the Git approach is no way to go for us because all the documentation has to be hosted on ASF side. Presently we violate this policy and I look forward we fix it pretty soon.

So, in general, all the documentation content has to become a part of Apache Ignite site and available from there. Here are some of the examples of another ASF projects:
http://spark.apache.org/docs/2.1.0/ <http://spark.apache.org/docs/2.1.0/>
https://zeppelin.apache.org/contribution/documentation.html <https://zeppelin.apache.org/contribution/documentation.html>
https://hadoop.apache.org/docs/r2.7.2/ <https://hadoop.apache.org/docs/r2.7.2/>

Are you aware of any ready-to-be-used documentation libs that can be easily reused by us?

—
Denis

> On Apr 11, 2017, at 2:02 AM, Pavel Tupitsyn <[hidden email]> wrote:
>
> Igniters,
>
> Currently we host documentation on
> apacheignite.readme.io (and also apacheignite-net.readme.io,
> apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).
>
> readme.io has a lot of problems mostly due to lack of proper version
> control:
> * Each "version" is just a copy. When fixing something, you have to update
> all versions.
> * No good way to review changes.
> * "Propose edit" functionality is a joke. You can only accept or reject an
> edit, no way to communicate with contributor, etc
>
> GitHub Pages solves all these problems:
> https://github.com/blog/2233-publish-your-project-documentation-with-github-pages
>
> Basically, we'll have a separate folder in our Git repository where
> documentation is stored in markdown format.
> This way the process for updating docs is exactly the same as any other
> code change.
> Pull request with new feature can contain the docs for this feature, and so
> on.
>
> Thoughts?

[Pavel Tupitsyn]

> Git approach is no way to go for us because all the documentation has to
be hosted on ASF side

Well, our Git repository [1] is hosted by ASF, isn't it?
GitHub pages just generates HTML from MarkDown via Jekyll [2] static site
generator.

I understand the concern about GitHub pages, though.
And Igor is right about different versions, seems like it may be not so
easy with GH pages.


So I propose to use Jekyll, but do not use GitHub pages:
* Keep documentation in our Git repository in MarkDown format
* Generate HTML when release comes out and upload it to ignite.apache.org
(same as we do for API docs [3])

Seems to be easy enough. The hardest part is to come up with a good
template.

Thoughts?


[1] https://git-wip-us.apache.org/repos/asf?p=ignite.git
[2] https://jekyllrb.com/
[3] https://ignite.apache.org/releases/1.8.0/javadoc/

On Tue, Apr 11, 2017 at 7:09 PM, Denis Magda <[hidden email]> wrote:

> Pavel,
>
> I totally agree that it’s becoming more and more inconvenient to run the
> documentation on readme.io <http://readme.io/>. At the same time the Git
> approach is no way to go for us because all the documentation has to be
> hosted on ASF side. Presently we violate this policy and I look forward we
> fix it pretty soon.
>
> So, in general, all the documentation content has to become a part of
> Apache Ignite site and available from there. Here are some of the examples
> of another ASF projects:
> http://spark.apache.org/docs/2.1.0/ <http://spark.apache.org/docs/2.1.0/>
> https://zeppelin.apache.org/contribution/documentation.html <
> https://zeppelin.apache.org/contribution/documentation.html>
> https://hadoop.apache.org/docs/r2.7.2/ <https://hadoop.apache.org/
> docs/r2.7.2/>
>
> Are you aware of any ready-to-be-used documentation libs that can be
> easily reused by us?
>
> —
> Denis
>
> > On Apr 11, 2017, at 2:02 AM, Pavel Tupitsyn <[hidden email]>
> wrote:
> >
> > Igniters,
> >
> > Currently we host documentation on
> > apacheignite.readme.io (and also apacheignite-net.readme.io,
> > apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).
> >
> > readme.io has a lot of problems mostly due to lack of proper version
> > control:
> > * Each "version" is just a copy. When fixing something, you have to
> update
> > all versions.
> > * No good way to review changes.
> > * "Propose edit" functionality is a joke. You can only accept or reject
> an
> > edit, no way to communicate with contributor, etc
> >
> > GitHub Pages solves all these problems:
> > https://github.com/blog/2233-publish-your-project-
> documentation-with-github-pages
> >
> > Basically, we'll have a separate folder in our Git repository where
> > documentation is stored in markdown format.
> > This way the process for updating docs is exactly the same as any other
> > code change.
> > Pull request with new feature can contain the docs for this feature, and
> so
> > on.
> >
> > Thoughts?
>
>

[dsetrakyan]

Pavel,

We all agree that the documentation should be in our GIT repo in either
Markdown or AsciiDoc format. However, it is a very big undertaking to
migrate it from readme and properly structure it. If anyone in the
community would volunteer, would be great.

D.

On Tue, Apr 11, 2017 at 9:36 PM, Pavel Tupitsyn <[hidden email]>
wrote:

> > Git approach is no way to go for us because all the documentation has to
> be hosted on ASF side
>
> Well, our Git repository [1] is hosted by ASF, isn't it?
> GitHub pages just generates HTML from MarkDown via Jekyll [2] static site
> generator.
>
> I understand the concern about GitHub pages, though.
> And Igor is right about different versions, seems like it may be not so
> easy with GH pages.
>
>
> So I propose to use Jekyll, but do not use GitHub pages:
> * Keep documentation in our Git repository in MarkDown format
> * Generate HTML when release comes out and upload it to ignite.apache.org
> (same as we do for API docs [3])
>
> Seems to be easy enough. The hardest part is to come up with a good
> template.
>
> Thoughts?
>
>
> [1] https://git-wip-us.apache.org/repos/asf?p=ignite.git
> [2] https://jekyllrb.com/
> [3] https://ignite.apache.org/releases/1.8.0/javadoc/
>
> On Tue, Apr 11, 2017 at 7:09 PM, Denis Magda <[hidden email]> wrote:
>
> > Pavel,
> >
> > I totally agree that it’s becoming more and more inconvenient to run the
> > documentation on readme.io <http://readme.io/>. At the same time the Git
> > approach is no way to go for us because all the documentation has to be
> > hosted on ASF side. Presently we violate this policy and I look forward
> we
> > fix it pretty soon.
> >
> > So, in general, all the documentation content has to become a part of
> > Apache Ignite site and available from there. Here are some of the
> examples
> > of another ASF projects:
> > http://spark.apache.org/docs/2.1.0/ <http://spark.apache.org/docs/2.1.0/
> >
> > https://zeppelin.apache.org/contribution/documentation.html <
> > https://zeppelin.apache.org/contribution/documentation.html>
> > https://hadoop.apache.org/docs/r2.7.2/ <https://hadoop.apache.org/
> > docs/r2.7.2/>
> >
> > Are you aware of any ready-to-be-used documentation libs that can be
> > easily reused by us?
> >
> > —
> > Denis
> >
> > > On Apr 11, 2017, at 2:02 AM, Pavel Tupitsyn <[hidden email]>
> > wrote:
> > >
> > > Igniters,
> > >
> > > Currently we host documentation on
> > > apacheignite.readme.io (and also apacheignite-net.readme.io,
> > > apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).
> > >
> > > readme.io has a lot of problems mostly due to lack of proper version
> > > control:
> > > * Each "version" is just a copy. When fixing something, you have to
> > update
> > > all versions.
> > > * No good way to review changes.
> > > * "Propose edit" functionality is a joke. You can only accept or reject
> > an
> > > edit, no way to communicate with contributor, etc
> > >
> > > GitHub Pages solves all these problems:
> > > https://github.com/blog/2233-publish-your-project-
> > documentation-with-github-pages
> > >
> > > Basically, we'll have a separate folder in our Git repository where
> > > documentation is stored in markdown format.
> > > This way the process for updating docs is exactly the same as any other
> > > code change.
> > > Pull request with new feature can contain the docs for this feature,
> and
> > so
> > > on.
> > >
> > > Thoughts?
> >
> >
>

[Konstantin Boudnik-2]

I hate to be that guy, but mentors warned this very project no to do
this in the first place. At least once [1] on the dev@, and a few
times off-line

[1] https://is.gd/ZRPOrH

Cos

--
  Take care,
Konstantin (Cos) Boudnik
2CAC 8312 4870 D885 8616  6115 220F 6980 1F27 E622

Disclaimer: Opinions expressed in this email are those of the author,
and do not necessarily represent the views of any company the author
might be affiliated with at the moment of writing.


On Tue, Apr 11, 2017 at 9:57 PM, Dmitriy Setrakyan
<[hidden email]> wrote:

> Pavel,
>
> We all agree that the documentation should be in our GIT repo in either
> Markdown or AsciiDoc format. However, it is a very big undertaking to
> migrate it from readme and properly structure it. If anyone in the
> community would volunteer, would be great.
>
> D.
>
> On Tue, Apr 11, 2017 at 9:36 PM, Pavel Tupitsyn <[hidden email]>
> wrote:
>
>> > Git approach is no way to go for us because all the documentation has to
>> be hosted on ASF side
>>
>> Well, our Git repository [1] is hosted by ASF, isn't it?
>> GitHub pages just generates HTML from MarkDown via Jekyll [2] static site
>> generator.
>>
>> I understand the concern about GitHub pages, though.
>> And Igor is right about different versions, seems like it may be not so
>> easy with GH pages.
>>
>>
>> So I propose to use Jekyll, but do not use GitHub pages:
>> * Keep documentation in our Git repository in MarkDown format
>> * Generate HTML when release comes out and upload it to ignite.apache.org
>> (same as we do for API docs [3])
>>
>> Seems to be easy enough. The hardest part is to come up with a good
>> template.
>>
>> Thoughts?
>>
>>
>> [1] https://git-wip-us.apache.org/repos/asf?p=ignite.git
>> [2] https://jekyllrb.com/
>> [3] https://ignite.apache.org/releases/1.8.0/javadoc/
>>
>> On Tue, Apr 11, 2017 at 7:09 PM, Denis Magda <[hidden email]> wrote:
>>
>> > Pavel,
>> >
>> > I totally agree that it’s becoming more and more inconvenient to run the
>> > documentation on readme.io <http://readme.io/>. At the same time the Git
>> > approach is no way to go for us because all the documentation has to be
>> > hosted on ASF side. Presently we violate this policy and I look forward
>> we
>> > fix it pretty soon.
>> >
>> > So, in general, all the documentation content has to become a part of
>> > Apache Ignite site and available from there. Here are some of the
>> examples
>> > of another ASF projects:
>> > http://spark.apache.org/docs/2.1.0/ <http://spark.apache.org/docs/2.1.0/
>> >
>> > https://zeppelin.apache.org/contribution/documentation.html <
>> > https://zeppelin.apache.org/contribution/documentation.html>
>> > https://hadoop.apache.org/docs/r2.7.2/ <https://hadoop.apache.org/
>> > docs/r2.7.2/>
>> >
>> > Are you aware of any ready-to-be-used documentation libs that can be
>> > easily reused by us?
>> >
>> > —
>> > Denis
>> >
>> > > On Apr 11, 2017, at 2:02 AM, Pavel Tupitsyn <[hidden email]>
>> > wrote:
>> > >
>> > > Igniters,
>> > >
>> > > Currently we host documentation on
>> > > apacheignite.readme.io (and also apacheignite-net.readme.io,
>> > > apacheignite-cpp.readme.io, apacheignite-mix.readme.io, etc).
>> > >
>> > > readme.io has a lot of problems mostly due to lack of proper version
>> > > control:
>> > > * Each "version" is just a copy. When fixing something, you have to
>> > update
>> > > all versions.
>> > > * No good way to review changes.
>> > > * "Propose edit" functionality is a joke. You can only accept or reject
>> > an
>> > > edit, no way to communicate with contributor, etc
>> > >
>> > > GitHub Pages solves all these problems:
>> > > https://github.com/blog/2233-publish-your-project-
>> > documentation-with-github-pages
>> > >
>> > > Basically, we'll have a separate folder in our Git repository where
>> > > documentation is stored in markdown format.
>> > > This way the process for updating docs is exactly the same as any other
>> > > code change.
>> > > Pull request with new feature can contain the docs for this feature,
>> and
>> > so
>> > > on.
>> > >
>> > > Thoughts?
>> >
>> >
>>

[dsetrakyan]

On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]> wrote:

> I hate to be that guy, but mentors warned this very project no to do
> this in the first place. At least once [1] on the dev@, and a few
> times off-line
>

Cos, no doubt this had come up before (after all, we did have very good
mentors during the incubation process).

Unfortunately, for tasks like this it is never a good time. I hope someone
in the community picks it up, or at least gets started on it.

[dmagda]

Created a ticket. I think the time to move from readme.io <http://readme.io/> has come. It’s becoming too challenging to live with it:
https://issues.apache.org/jira/browse/IGNITE-7595 <https://issues.apache.org/jira/browse/IGNITE-7595>

—
Denis

> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <[hidden email]> wrote:
>
> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]> wrote:
>
>> I hate to be that guy, but mentors warned this very project no to do
>> this in the first place. At least once [1] on the dev@, and a few
>> times off-line
>>
>
> Cos, no doubt this had come up before (after all, we did have very good
> mentors during the incubation process).
>
> Unfortunately, for tasks like this it is never a good time. I hope someone
> in the community picks it up, or at least gets started on it.

[Pavel Tupitsyn]

Good news, Denis.

By the way, readme.io uses some kind of markdown dialect, and they have
"export" feature,
so it should be possible to move to some markdown-based system like Jekyll
without too much hassle.

On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]> wrote:

> Created a ticket. I think the time to move from readme.io <
> http://readme.io/> has come. It’s becoming too challenging to live with
> it:
> https://issues.apache.org/jira/browse/IGNITE-7595 <
> https://issues.apache.org/jira/browse/IGNITE-7595>
>
> —
> Denis
>
> > On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <[hidden email]>
> wrote:
> >
> > On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]>
> wrote:
> >
> >> I hate to be that guy, but mentors warned this very project no to do
> >> this in the first place. At least once [1] on the dev@, and a few
> >> times off-line
> >>
> >
> > Cos, no doubt this had come up before (after all, we did have very good
> > mentors during the incubation process).
> >
> > Unfortunately, for tasks like this it is never a good time. I hope
> someone
> > in the community picks it up, or at least gets started on it.
>
>

[dsetrakyan]

Guys, as I have been saying all along, we need to identify a documentation
system we want to move to. Once we do that, we can plan how to move off of
readme.

Again, the most important benefit readme has is instantaneous documentation
update. However, on the downside, they do not integrate with Git well, and
ASF wants all its projects to keep the documentation in Apache Git.

Does anyone have suggestions?

D.

On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <[hidden email]> wrote:

> Good news, Denis.
>
> By the way, readme.io uses some kind of markdown dialect, and they have
> "export" feature,
> so it should be possible to move to some markdown-based system like Jekyll
> without too much hassle.
>
> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]> wrote:
>
> > Created a ticket. I think the time to move from readme.io <
> > http://readme.io/> has come. It’s becoming too challenging to live with
> > it:
> > https://issues.apache.org/jira/browse/IGNITE-7595 <
> > https://issues.apache.org/jira/browse/IGNITE-7595>
> >
> > —
> > Denis
> >
> > > On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <[hidden email]>
> > wrote:
> > >
> > > On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]>
> > wrote:
> > >
> > >> I hate to be that guy, but mentors warned this very project no to do
> > >> this in the first place. At least once [1] on the dev@, and a few
> > >> times off-line
> > >>
> > >
> > > Cos, no doubt this had come up before (after all, we did have very good
> > > mentors during the incubation process).
> > >
> > > Unfortunately, for tasks like this it is never a good time. I hope
> > someone
> > > in the community picks it up, or at least gets started on it.
> >
> >
>

[dmagda]

Dmitriy,

We will do a research before jumping off the readme.io <http://readme.io/> train.

In addition, to the technical issues outlined in the ticket, readme.io <http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index only the latest docs' version! Ignore specific versions”. As a result, the Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that pop up at the top of the search. You know this annoying thing better than me :)

—
Denis

> On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <[hidden email]> wrote:
>
> Guys, as I have been saying all along, we need to identify a documentation
> system we want to move to. Once we do that, we can plan how to move off of
> readme.
>
> Again, the most important benefit readme has is instantaneous documentation
> update. However, on the downside, they do not integrate with Git well, and
> ASF wants all its projects to keep the documentation in Apache Git.
>
> Does anyone have suggestions?
>
> D.
>
> On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <[hidden email]> wrote:
>
>> Good news, Denis.
>>
>> By the way, readme.io uses some kind of markdown dialect, and they have
>> "export" feature,
>> so it should be possible to move to some markdown-based system like Jekyll
>> without too much hassle.
>>
>> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]> wrote:
>>
>>> Created a ticket. I think the time to move from readme.io <
>>> http://readme.io/> has come. It’s becoming too challenging to live with
>>> it:
>>> https://issues.apache.org/jira/browse/IGNITE-7595 <
>>> https://issues.apache.org/jira/browse/IGNITE-7595>
>>>
>>> —
>>> Denis
>>>
>>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <[hidden email]>
>>> wrote:
>>>>
>>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]>
>>> wrote:
>>>>
>>>>> I hate to be that guy, but mentors warned this very project no to do
>>>>> this in the first place. At least once [1] on the dev@, and a few
>>>>> times off-line
>>>>>
>>>>
>>>> Cos, no doubt this had come up before (after all, we did have very good
>>>> mentors during the incubation process).
>>>>
>>>> Unfortunately, for tasks like this it is never a good time. I hope
>>> someone
>>>> in the community picks it up, or at least gets started on it.
>>>
>>>
>>

[Pavel Tupitsyn]

I did some research for my blog some time ago, and proposal is:

* Export markdown from Readme.io (tweak as necessary, code samples etc)
* Store markdown in git. Separate branch for each Ignite version
(ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
* Use Jekyll to generate HTML from markdown
* Host documentation on ignite.apache.org (upload is via SVN, any committer
has rights, *changes are instant*)

On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <[hidden email]> wrote:

> Dmitriy,
>
> We will do a research before jumping off the readme.io <http://readme.io/>
> train.
>
> In addition, to the technical issues outlined in the ticket, readme.io <
> http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index
> only the latest docs' version! Ignore specific versions”. As a result, the
> Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that
> pop up at the top of the search. You know this annoying thing better than
> me :)
>
> —
> Denis
>
> > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <[hidden email]>
> wrote:
> >
> > Guys, as I have been saying all along, we need to identify a
> documentation
> > system we want to move to. Once we do that, we can plan how to move off
> of
> > readme.
> >
> > Again, the most important benefit readme has is instantaneous
> documentation
> > update. However, on the downside, they do not integrate with Git well,
> and
> > ASF wants all its projects to keep the documentation in Apache Git.
> >
> > Does anyone have suggestions?
> >
> > D.
> >
> > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <[hidden email]>
> wrote:
> >
> >> Good news, Denis.
> >>
> >> By the way, readme.io uses some kind of markdown dialect, and they have
> >> "export" feature,
> >> so it should be possible to move to some markdown-based system like
> Jekyll
> >> without too much hassle.
> >>
> >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]> wrote:
> >>
> >>> Created a ticket. I think the time to move from readme.io <
> >>> http://readme.io/> has come. It’s becoming too challenging to live
> with
> >>> it:
> >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> >>>
> >>> —
> >>> Denis
> >>>
> >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <[hidden email]
> >
> >>> wrote:
> >>>>
> >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]>
> >>> wrote:
> >>>>
> >>>>> I hate to be that guy, but mentors warned this very project no to do
> >>>>> this in the first place. At least once [1] on the dev@, and a few
> >>>>> times off-line
> >>>>>
> >>>>
> >>>> Cos, no doubt this had come up before (after all, we did have very
> good
> >>>> mentors during the incubation process).
> >>>>
> >>>> Unfortunately, for tasks like this it is never a good time. I hope
> >>> someone
> >>>> in the community picks it up, or at least gets started on it.
> >>>
> >>>
> >>
>
>

[Alexey Kuznetsov]

Pavel,

Do I correctly understand, that if I find a typo in docs, I should commit
fix to master and cherry-pick to all relevant branches?

On Fri, Feb 2, 2018 at 2:28 PM, Pavel Tupitsyn <[hidden email]> wrote:

> I did some research for my blog some time ago, and proposal is:
>
> * Export markdown from Readme.io (tweak as necessary, code samples etc)
> * Store markdown in git. Separate branch for each Ignite version
> (ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
> * Use Jekyll to generate HTML from markdown
> * Host documentation on ignite.apache.org (upload is via SVN, any
> committer
> has rights, *changes are instant*)
>
> On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <[hidden email]> wrote:
>
> > Dmitriy,
> >
> > We will do a research before jumping off the readme.io <
> http://readme.io/>
> > train.
> >
> > In addition, to the technical issues outlined in the ticket, readme.io <
> > http://readme.io/> doesn’t give a way to tell Google “Hey, Google, index
> > only the latest docs' version! Ignore specific versions”. As a result,
> the
> > Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages that
> > pop up at the top of the search. You know this annoying thing better than
> > me :)
> >
> > —
> > Denis
> >
> > > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <[hidden email]>
> > wrote:
> > >
> > > Guys, as I have been saying all along, we need to identify a
> > documentation
> > > system we want to move to. Once we do that, we can plan how to move off
> > of
> > > readme.
> > >
> > > Again, the most important benefit readme has is instantaneous
> > documentation
> > > update. However, on the downside, they do not integrate with Git well,
> > and
> > > ASF wants all its projects to keep the documentation in Apache Git.
> > >
> > > Does anyone have suggestions?
> > >
> > > D.
> > >
> > > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <[hidden email]>
> > wrote:
> > >
> > >> Good news, Denis.
> > >>
> > >> By the way, readme.io uses some kind of markdown dialect, and they
> have
> > >> "export" feature,
> > >> so it should be possible to move to some markdown-based system like
> > Jekyll
> > >> without too much hassle.
> > >>
> > >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]>
> wrote:
> > >>
> > >>> Created a ticket. I think the time to move from readme.io <
> > >>> http://readme.io/> has come. It’s becoming too challenging to live
> > with
> > >>> it:
> > >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> > >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> > >>>
> > >>> —
> > >>> Denis
> > >>>
> > >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <
> [hidden email]
> > >
> > >>> wrote:
> > >>>>
> > >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <[hidden email]
> >
> > >>> wrote:
> > >>>>
> > >>>>> I hate to be that guy, but mentors warned this very project no to
> do
> > >>>>> this in the first place. At least once [1] on the dev@, and a few
> > >>>>> times off-line
> > >>>>>
> > >>>>
> > >>>> Cos, no doubt this had come up before (after all, we did have very
> > good
> > >>>> mentors during the incubation process).
> > >>>>
> > >>>> Unfortunately, for tasks like this it is never a good time. I hope
> > >>> someone
> > >>>> in the community picks it up, or at least gets started on it.
> > >>>
> > >>>
> > >>
> >
> >
>

--
Alexey Kuznetsov

[Pavel Tupitsyn]

Alexey, yes, cherry-pick to branches and update website for each version as
well (this can be automated with a script)
Still a bit cumbersome, but at least you don't have to make the same edit
multiple times.

On Fri, Feb 2, 2018 at 10:59 AM, Alexey Kuznetsov <[hidden email]>
wrote:

> Pavel,
>
> Do I correctly understand, that if I find a typo in docs, I should commit
> fix to master and cherry-pick to all relevant branches?
>
> On Fri, Feb 2, 2018 at 2:28 PM, Pavel Tupitsyn <[hidden email]>
> wrote:
>
> > I did some research for my blog some time ago, and proposal is:
> >
> > * Export markdown from Readme.io (tweak as necessary, code samples etc)
> > * Store markdown in git. Separate branch for each Ignite version
> > (ignite-2.3-docs, ignite-2.4-docs, etc). Future version is in master.
> > * Use Jekyll to generate HTML from markdown
> > * Host documentation on ignite.apache.org (upload is via SVN, any
> > committer
> > has rights, *changes are instant*)
> >
> > On Fri, Feb 2, 2018 at 2:05 AM, Denis Magda <[hidden email]> wrote:
> >
> > > Dmitriy,
> > >
> > > We will do a research before jumping off the readme.io <
> > http://readme.io/>
> > > train.
> > >
> > > In addition, to the technical issues outlined in the ticket, readme.io
> <
> > > http://readme.io/> doesn’t give a way to tell Google “Hey, Google,
> index
> > > only the latest docs' version! Ignore specific versions”. As a result,
> > the
> > > Internet is flooded with Ignite 1.1, 1.7, 1.9 versions of the pages
> that
> > > pop up at the top of the search. You know this annoying thing better
> than
> > > me :)
> > >
> > > —
> > > Denis
> > >
> > > > On Feb 1, 2018, at 1:39 PM, Dmitriy Setrakyan <[hidden email]
> >
> > > wrote:
> > > >
> > > > Guys, as I have been saying all along, we need to identify a
> > > documentation
> > > > system we want to move to. Once we do that, we can plan how to move
> off
> > > of
> > > > readme.
> > > >
> > > > Again, the most important benefit readme has is instantaneous
> > > documentation
> > > > update. However, on the downside, they do not integrate with Git
> well,
> > > and
> > > > ASF wants all its projects to keep the documentation in Apache Git.
> > > >
> > > > Does anyone have suggestions?
> > > >
> > > > D.
> > > >
> > > > On Thu, Feb 1, 2018 at 5:57 AM, Pavel Tupitsyn <[hidden email]
> >
> > > wrote:
> > > >
> > > >> Good news, Denis.
> > > >>
> > > >> By the way, readme.io uses some kind of markdown dialect, and they
> > have
> > > >> "export" feature,
> > > >> so it should be possible to move to some markdown-based system like
> > > Jekyll
> > > >> without too much hassle.
> > > >>
> > > >> On Thu, Feb 1, 2018 at 2:18 AM, Denis Magda <[hidden email]>
> > wrote:
> > > >>
> > > >>> Created a ticket. I think the time to move from readme.io <
> > > >>> http://readme.io/> has come. It’s becoming too challenging to live
> > > with
> > > >>> it:
> > > >>> https://issues.apache.org/jira/browse/IGNITE-7595 <
> > > >>> https://issues.apache.org/jira/browse/IGNITE-7595>
> > > >>>
> > > >>> —
> > > >>> Denis
> > > >>>
> > > >>>> On Apr 13, 2017, at 8:25 AM, Dmitriy Setrakyan <
> > [hidden email]
> > > >
> > > >>> wrote:
> > > >>>>
> > > >>>> On Wed, Apr 12, 2017 at 8:52 PM, Konstantin Boudnik <
> [hidden email]
> > >
> > > >>> wrote:
> > > >>>>
> > > >>>>> I hate to be that guy, but mentors warned this very project no to
> > do
> > > >>>>> this in the first place. At least once [1] on the dev@, and a
> few
> > > >>>>> times off-line
> > > >>>>>
> > > >>>>
> > > >>>> Cos, no doubt this had come up before (after all, we did have very
> > > good
> > > >>>> mentors during the incubation process).
> > > >>>>
> > > >>>> Unfortunately, for tasks like this it is never a good time. I hope
> > > >>> someone
> > > >>>> in the community picks it up, or at least gets started on it.
> > > >>>
> > > >>>
> > > >>
> > >
> > >
> >
>
>
>
> --
> Alexey Kuznetsov
>

[endianignite]

I noticed that Facebook open-sourced a documentation platform last month,
https://docusaurus.io/, which may be worth considering.





--
Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/

[dsetrakyan]

I think docusaurus.io could work for us. Denis, what do you think?

On Fri, Feb 2, 2018 at 3:10 AM, endianignite <[hidden email]> wrote:

> I noticed that Facebook open-sourced a documentation platform last month,
> https://docusaurus.io/, which may be worth considering.
>
>
>
>
>
> --
> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
>

[dmagda]

Looks promising. Thanks for sharing. Updated the ticket.

—
Denis

> On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <[hidden email]> wrote:
>
> I think docusaurus.io could work for us. Denis, what do you think?
>
> On Fri, Feb 2, 2018 at 3:10 AM, endianignite <[hidden email]> wrote:
>
>> I noticed that Facebook open-sourced a documentation platform last month,
>> https://docusaurus.io/, which may be worth considering.
>>
>>
>>
>>
>>
>> --
>> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
>>

[Prachi Garg]

I looked into Docusaurus and GitBook. I liked Docusaurus better because it
allows publishing to github pages or other static files hosts, and various
other features. My findings are mentioned in the ticket -
https://issues.apache.org/jira/browse/IGNITE-7595 .

On Fri, Feb 2, 2018 at 2:42 PM, Denis Magda <[hidden email]> wrote:

> Looks promising. Thanks for sharing. Updated the ticket.
>
> —
> Denis
>
> > On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <[hidden email]>
> wrote:
> >
> > I think docusaurus.io could work for us. Denis, what do you think?
> >
> > On Fri, Feb 2, 2018 at 3:10 AM, endianignite <[hidden email]>
> wrote:
> >
> >> I noticed that Facebook open-sourced a documentation platform last
> month,
> >> https://docusaurus.io/, which may be worth considering.
> >>
> >>
> >>
> >>
> >>
> >> --
> >> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
> >>
>
>

[dmagda]

Copied from the ticket.

*Feature*

*Docusaurus*

*GitBook*

*Free*

Yes (FaceBook open source project)

Yes (Free version only allows 5 contributors)

*Setup and Installation*

Easy installation and configuration steps.

Initial setup is easy; Need to look around for customization.

*Standard Markdown*

Yes

Yes

*Versioning*

Yes (automatic)

Yes (via github branching)

*Search*

Yes

Yes

*Table of contents for pages*

Yes (out-of-the-box)

No (Default theme does not support it; maybe availble through external
plugin)

*Support child pages*

No

Yes

*Allows website design customization*



Yes

Limited; Use external theme plugins.

*Top Nav bar & Footer*

Yes

No

*Live server(localhost) to view changes*

Yes

Yes

*Tab navigation on pages*

No tab navigation support out-of-the box.

Note: It is possible to create tabs using external React JS plugin or
implementing a React component. For example, React Native uses Docusaurus
and have implemented tabs-
http://facebook.github.io/react-native/docs/getting-started.html



No tab navigation support out-of-the box.

Note: It is possible to create tabs using external GitBook plugins.



*Publishing the website*

Publish the documentation site to Github pages or other static file hosts.



Publish the documentation site to git.gitbook.io (or custom domain) or
other static file hosts.



*Store all markdown files on github*

Yes

Yes

*Editor*

Use text editor. Alternatively, IntelliJ can be used, it has a plugin for
Markdown.

Provides desktop and online editor.

*Active support and development*

Yes. Facebook engineers are pretty responsive!

Hmm.. some people are wondering if they are still alive :-)


Prachi, thanks for the research and summary. I cast my ballot for
Docusaurus. It has much more prominent benefits over

GitBook such as a table of content, more advanced visual customization,
ability to edit from IntelliJ, and support by Facebook

engineers -- probably that's the way for Ignite to get installed at
Facebook in the future.


--
Denis

On Tue, Mar 20, 2018 at 4:38 PM, Prachi Garg <[hidden email]> wrote:

> I looked into Docusaurus and GitBook. I liked Docusaurus better because it
> allows publishing to github pages or other static files hosts, and various
> other features. My findings are mentioned in the ticket -
> https://issues.apache.org/jira/browse/IGNITE-7595 .
>
> On Fri, Feb 2, 2018 at 2:42 PM, Denis Magda <[hidden email]> wrote:
>
> > Looks promising. Thanks for sharing. Updated the ticket.
> >
> > —
> > Denis
> >
> > > On Feb 2, 2018, at 2:25 PM, Dmitriy Setrakyan <[hidden email]>
> > wrote:
> > >
> > > I think docusaurus.io could work for us. Denis, what do you think?
> > >
> > > On Fri, Feb 2, 2018 at 3:10 AM, endianignite <[hidden email]>
> > wrote:
> > >
> > >> I noticed that Facebook open-sourced a documentation platform last
> > month,
> > >> https://docusaurus.io/, which may be worth considering.
> > >>
> > >>
> > >>
> > >>
> > >>
> > >> --
> > >> Sent from: http://apache-ignite-developers.2346864.n4.nabble.com/
> > >>
> >
> >
>

[dsetrakyan]

Does docusaurus work with GitHub only, or with Git in general? In Apache
GitHub is used as a mirror of an internal Git repo, which is the primary
source of data.

D.