You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Dmitriy Setrakyan <ds...@apache.org> on 2015/02/09 07:25:23 UTC
New home for Ignite documentation
Hello Igniters,
I think I have found a pretty cool home for our documentation:
http://apacheignite.readme.io/v1.0/docs
https://readme.io is nice enough to host open source documentation for
free, and I like the editability and friendliness of their UI.
I have added most of the committers as admins to the documentation wiki.
Feel free to start contributing pages.
D.
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
It depends. To me. it is great if the docs are sitting right there with the
source code and I don't need to go around to find the right version. And in
many cases this is how that got handled in Apache projects.
But it is really up to the people who're developing the project how you want
to deal with it.
Cos
On Tue, Feb 10, 2015 at 02:09PM, Dmitriy Setrakyan wrote:
> These docs are auto-generated during the build and are not part of the
> source code. I don't really see why we would make it part of the release
> tar ball. However, the maven task that generates it will be part of the
> release.
>
> Makes sense?
>
> D.
>
> On Tue, Feb 10, 2015 at 1:54 PM, Konstantin Boudnik <co...@apache.org> wrote:
>
> > The docs are still going to be a part of a release tarball, right?
> >
> > Cos
> >
> > On Tue, Feb 10, 2015 at 01:15PM, Dmitriy Setrakyan wrote:
> > > Java and scala docs should be uploaded to the website. We can do so by
> > > simply committing them to SVN into the following folders:
> > >
> > > - releases/javadoc/1.0
> > > - releases/scaladoc/1.0
> > >
> > > The SVN repo is at:
> > > https://svn.apache.org/repos/asf/incubator/ignite/site/trunk
> > >
> > > Can someone integrate it into the build process?
> > >
> > > D.
> > >
> > > On Tue, Feb 10, 2015 at 1:05 PM, Sergey Kozlov <sk...@gridgain.com>
> > wrote:
> > >
> > > > What's about upload java/scala docs there?
> > > >
> > > > On Mon, Feb 9, 2015 at 6:16 PM, Dmitriy Setrakyan <
> > dsetrakyan@apache.org>
> > > > wrote:
> > > >
> > > > > We should add it. Please click on "Suggested Edits" link and mention
> > the
> > > > > missing artifacts.
> > > > >
> > > > > D.
> > > > >
> > > > > On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com>
> > > > > wrote:
> > > > >
> > > > > > Hi Dmitriy,
> > > > > >
> > > > > > Is it okey, that I don't see "ignite-geospatial" module under "The
> > > > > > following modules are available:" on "Maven Setup" tab?
> > > > > >
> > > > > > Artem Shutak
> > > > > > GridGain Systems
> > > > > > www.gridgain.com
> > > > > >
> > > > > > On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <
> > > > dsetrakyan@apache.org
> > > > > >
> > > > > > wrote:
> > > > > >
> > > > > > > Hello Igniters,
> > > > > > >
> > > > > > > I think I have found a pretty cool home for our documentation:
> > > > > > > http://apacheignite.readme.io/v1.0/docs
> > > > > > >
> > > > > > > https://readme.io is nice enough to host open source
> > documentation
> > > > for
> > > > > > > free, and I like the editability and friendliness of their UI.
> > > > > > >
> > > > > > > I have added most of the committers as admins to the
> > documentation
> > > > > wiki.
> > > > > > >
> > > > > > > Feel free to start contributing pages.
> > > > > > >
> > > > > > > D.
> > > > > > >
> > > > > >
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Sergey Kozlov
> > > > GridGain Systems
> > > > www.gridgain.com
> > > >
> >
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
These docs are auto-generated during the build and are not part of the
source code. I don't really see why we would make it part of the release
tar ball. However, the maven task that generates it will be part of the
release.
Makes sense?
D.
On Tue, Feb 10, 2015 at 1:54 PM, Konstantin Boudnik <co...@apache.org> wrote:
> The docs are still going to be a part of a release tarball, right?
>
> Cos
>
> On Tue, Feb 10, 2015 at 01:15PM, Dmitriy Setrakyan wrote:
> > Java and scala docs should be uploaded to the website. We can do so by
> > simply committing them to SVN into the following folders:
> >
> > - releases/javadoc/1.0
> > - releases/scaladoc/1.0
> >
> > The SVN repo is at:
> > https://svn.apache.org/repos/asf/incubator/ignite/site/trunk
> >
> > Can someone integrate it into the build process?
> >
> > D.
> >
> > On Tue, Feb 10, 2015 at 1:05 PM, Sergey Kozlov <sk...@gridgain.com>
> wrote:
> >
> > > What's about upload java/scala docs there?
> > >
> > > On Mon, Feb 9, 2015 at 6:16 PM, Dmitriy Setrakyan <
> dsetrakyan@apache.org>
> > > wrote:
> > >
> > > > We should add it. Please click on "Suggested Edits" link and mention
> the
> > > > missing artifacts.
> > > >
> > > > D.
> > > >
> > > > On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com>
> > > > wrote:
> > > >
> > > > > Hi Dmitriy,
> > > > >
> > > > > Is it okey, that I don't see "ignite-geospatial" module under "The
> > > > > following modules are available:" on "Maven Setup" tab?
> > > > >
> > > > > Artem Shutak
> > > > > GridGain Systems
> > > > > www.gridgain.com
> > > > >
> > > > > On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <
> > > dsetrakyan@apache.org
> > > > >
> > > > > wrote:
> > > > >
> > > > > > Hello Igniters,
> > > > > >
> > > > > > I think I have found a pretty cool home for our documentation:
> > > > > > http://apacheignite.readme.io/v1.0/docs
> > > > > >
> > > > > > https://readme.io is nice enough to host open source
> documentation
> > > for
> > > > > > free, and I like the editability and friendliness of their UI.
> > > > > >
> > > > > > I have added most of the committers as admins to the
> documentation
> > > > wiki.
> > > > > >
> > > > > > Feel free to start contributing pages.
> > > > > >
> > > > > > D.
> > > > > >
> > > > >
> > > >
> > >
> > >
> > >
> > > --
> > > Sergey Kozlov
> > > GridGain Systems
> > > www.gridgain.com
> > >
>
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
The docs are still going to be a part of a release tarball, right?
Cos
On Tue, Feb 10, 2015 at 01:15PM, Dmitriy Setrakyan wrote:
> Java and scala docs should be uploaded to the website. We can do so by
> simply committing them to SVN into the following folders:
>
> - releases/javadoc/1.0
> - releases/scaladoc/1.0
>
> The SVN repo is at:
> https://svn.apache.org/repos/asf/incubator/ignite/site/trunk
>
> Can someone integrate it into the build process?
>
> D.
>
> On Tue, Feb 10, 2015 at 1:05 PM, Sergey Kozlov <sk...@gridgain.com> wrote:
>
> > What's about upload java/scala docs there?
> >
> > On Mon, Feb 9, 2015 at 6:16 PM, Dmitriy Setrakyan <ds...@apache.org>
> > wrote:
> >
> > > We should add it. Please click on "Suggested Edits" link and mention the
> > > missing artifacts.
> > >
> > > D.
> > >
> > > On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com>
> > > wrote:
> > >
> > > > Hi Dmitriy,
> > > >
> > > > Is it okey, that I don't see "ignite-geospatial" module under "The
> > > > following modules are available:" on "Maven Setup" tab?
> > > >
> > > > Artem Shutak
> > > > GridGain Systems
> > > > www.gridgain.com
> > > >
> > > > On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <
> > dsetrakyan@apache.org
> > > >
> > > > wrote:
> > > >
> > > > > Hello Igniters,
> > > > >
> > > > > I think I have found a pretty cool home for our documentation:
> > > > > http://apacheignite.readme.io/v1.0/docs
> > > > >
> > > > > https://readme.io is nice enough to host open source documentation
> > for
> > > > > free, and I like the editability and friendliness of their UI.
> > > > >
> > > > > I have added most of the committers as admins to the documentation
> > > wiki.
> > > > >
> > > > > Feel free to start contributing pages.
> > > > >
> > > > > D.
> > > > >
> > > >
> > >
> >
> >
> >
> > --
> > Sergey Kozlov
> > GridGain Systems
> > www.gridgain.com
> >
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
Java and scala docs should be uploaded to the website. We can do so by
simply committing them to SVN into the following folders:
- releases/javadoc/1.0
- releases/scaladoc/1.0
The SVN repo is at:
https://svn.apache.org/repos/asf/incubator/ignite/site/trunk
Can someone integrate it into the build process?
D.
On Tue, Feb 10, 2015 at 1:05 PM, Sergey Kozlov <sk...@gridgain.com> wrote:
> What's about upload java/scala docs there?
>
> On Mon, Feb 9, 2015 at 6:16 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
>
> > We should add it. Please click on "Suggested Edits" link and mention the
> > missing artifacts.
> >
> > D.
> >
> > On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com>
> > wrote:
> >
> > > Hi Dmitriy,
> > >
> > > Is it okey, that I don't see "ignite-geospatial" module under "The
> > > following modules are available:" on "Maven Setup" tab?
> > >
> > > Artem Shutak
> > > GridGain Systems
> > > www.gridgain.com
> > >
> > > On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <
> dsetrakyan@apache.org
> > >
> > > wrote:
> > >
> > > > Hello Igniters,
> > > >
> > > > I think I have found a pretty cool home for our documentation:
> > > > http://apacheignite.readme.io/v1.0/docs
> > > >
> > > > https://readme.io is nice enough to host open source documentation
> for
> > > > free, and I like the editability and friendliness of their UI.
> > > >
> > > > I have added most of the committers as admins to the documentation
> > wiki.
> > > >
> > > > Feel free to start contributing pages.
> > > >
> > > > D.
> > > >
> > >
> >
>
>
>
> --
> Sergey Kozlov
> GridGain Systems
> www.gridgain.com
>
Re: New home for Ignite documentation
Posted by Sergey Kozlov <sk...@gridgain.com>.
What's about upload java/scala docs there?
On Mon, Feb 9, 2015 at 6:16 PM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> We should add it. Please click on "Suggested Edits" link and mention the
> missing artifacts.
>
> D.
>
> On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com>
> wrote:
>
> > Hi Dmitriy,
> >
> > Is it okey, that I don't see "ignite-geospatial" module under "The
> > following modules are available:" on "Maven Setup" tab?
> >
> > Artem Shutak
> > GridGain Systems
> > www.gridgain.com
> >
> > On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <dsetrakyan@apache.org
> >
> > wrote:
> >
> > > Hello Igniters,
> > >
> > > I think I have found a pretty cool home for our documentation:
> > > http://apacheignite.readme.io/v1.0/docs
> > >
> > > https://readme.io is nice enough to host open source documentation for
> > > free, and I like the editability and friendliness of their UI.
> > >
> > > I have added most of the committers as admins to the documentation
> wiki.
> > >
> > > Feel free to start contributing pages.
> > >
> > > D.
> > >
> >
>
--
Sergey Kozlov
GridGain Systems
www.gridgain.com
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
We should add it. Please click on "Suggested Edits" link and mention the
missing artifacts.
D.
On Mon, Feb 9, 2015 at 4:02 AM, Artiom Shutak <as...@gridgain.com> wrote:
> Hi Dmitriy,
>
> Is it okey, that I don't see "ignite-geospatial" module under "The
> following modules are available:" on "Maven Setup" tab?
>
> Artem Shutak
> GridGain Systems
> www.gridgain.com
>
> On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
>
> > Hello Igniters,
> >
> > I think I have found a pretty cool home for our documentation:
> > http://apacheignite.readme.io/v1.0/docs
> >
> > https://readme.io is nice enough to host open source documentation for
> > free, and I like the editability and friendliness of their UI.
> >
> > I have added most of the committers as admins to the documentation wiki.
> >
> > Feel free to start contributing pages.
> >
> > D.
> >
>
Re: New home for Ignite documentation
Posted by Artiom Shutak <as...@gridgain.com>.
Hi Dmitriy,
Is it okey, that I don't see "ignite-geospatial" module under "The
following modules are available:" on "Maven Setup" tab?
Artem Shutak
GridGain Systems
www.gridgain.com
On Mon, Feb 9, 2015 at 9:25 AM, Dmitriy Setrakyan <ds...@apache.org>
wrote:
> Hello Igniters,
>
> I think I have found a pretty cool home for our documentation:
> http://apacheignite.readme.io/v1.0/docs
>
> https://readme.io is nice enough to host open source documentation for
> free, and I like the editability and friendliness of their UI.
>
> I have added most of the committers as admins to the documentation wiki.
>
> Feel free to start contributing pages.
>
> D.
>
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
On Wed, Mar 04, 2015 at 11:55PM, Branko Čibej wrote:
> On 04.03.2015 23:47, Konstantin Boudnik wrote:
> > On Wed, Mar 04, 2015 at 11:41PM, Branko Čibej wrote:
> >> On 04.03.2015 23:33, Konstantin Boudnik wrote:
> >>> On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
> >>>> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
> >>>>
> >>>>> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
> >>>>>> readme.io is a very cool documentation platform which gives free web
> >>>>>> hosting, versioning, and sexy looks to open source projects, including
> >>>>>> Apache projects. It stores documentation in a regular markdown format,
> >>>>> and
> >>>>>> I will add the MD files to the GIT tree before doing the next release.
> >>>>> This
> >>>>>> way readme.io will be the copy of the documentation stored in github. I
> >>>>> You meant 'stored in Apache git", didn't you?
> >>>>>
> >>>> Yes, the Apache git.
> >>> It seems to be satisfactory solutio as far as we keep the original docs source
> >>> in Apache, no?
> >> There are a couple open questions here:
> >>
> >> * While all committers can update the docs, all committers should also
> >> be able to manage the readme.io site. AFAIK there's no automated way
> >> to achieve that, and no documented way for adding site
> >> administrators. That's kind of a bad start.
> > if readme.io would only be a "mirror" of real docs that issue will sorta go
> > away, right? As no one would need to manage or change the site?
>
> But that's not the case. Docs in git != online docs, so it's not a
> mirror, it's the only online source.
True, unless there's a way to transpose the docs from source code to something
like (c)wiki we might have a problem.
> Tecnically, you can view the docs with 'cat | less' and use your
> imagination to interpret the CSS and markup ...
My imagination works better than that - I can open a disk file in my FF ;) And
let it do the rest.
Cos
Re: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 04.03.2015 23:47, Konstantin Boudnik wrote:
> On Wed, Mar 04, 2015 at 11:41PM, Branko Čibej wrote:
>> On 04.03.2015 23:33, Konstantin Boudnik wrote:
>>> On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
>>>> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
>>>>
>>>>> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
>>>>>> readme.io is a very cool documentation platform which gives free web
>>>>>> hosting, versioning, and sexy looks to open source projects, including
>>>>>> Apache projects. It stores documentation in a regular markdown format,
>>>>> and
>>>>>> I will add the MD files to the GIT tree before doing the next release.
>>>>> This
>>>>>> way readme.io will be the copy of the documentation stored in github. I
>>>>> You meant 'stored in Apache git", didn't you?
>>>>>
>>>> Yes, the Apache git.
>>> It seems to be satisfactory solutio as far as we keep the original docs source
>>> in Apache, no?
>> There are a couple open questions here:
>>
>> * While all committers can update the docs, all committers should also
>> be able to manage the readme.io site. AFAIK there's no automated way
>> to achieve that, and no documented way for adding site
>> administrators. That's kind of a bad start.
> if readme.io would only be a "mirror" of real docs that issue will sorta go
> away, right? As no one would need to manage or change the site?
But that's not the case. Docs in git != online docs, so it's not a
mirror, it's the only online source.
Tecnically, you can view the docs with 'cat | less' and use your
imagination to interpret the CSS and markup ...
-- Brane
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
On Wed, Mar 04, 2015 at 11:41PM, Branko Čibej wrote:
> On 04.03.2015 23:33, Konstantin Boudnik wrote:
> > On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
> >> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
> >>
> >>> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
> >>>> readme.io is a very cool documentation platform which gives free web
> >>>> hosting, versioning, and sexy looks to open source projects, including
> >>>> Apache projects. It stores documentation in a regular markdown format,
> >>> and
> >>>> I will add the MD files to the GIT tree before doing the next release.
> >>> This
> >>>> way readme.io will be the copy of the documentation stored in github. I
> >>> You meant 'stored in Apache git", didn't you?
> >>>
> >> Yes, the Apache git.
> > It seems to be satisfactory solutio as far as we keep the original docs source
> > in Apache, no?
>
> There are a couple open questions here:
>
> * While all committers can update the docs, all committers should also
> be able to manage the readme.io site. AFAIK there's no automated way
> to achieve that, and no documented way for adding site
> administrators. That's kind of a bad start.
if readme.io would only be a "mirror" of real docs that issue will sorta go
away, right? As no one would need to manage or change the site?
> * Readme.io is the /only/ online source of the docs, apparently. The
> Incubator site links there, and there's no other way to see the docs
> short of checking out the source. So ... what if readme.io goes away?
Yeah, that's an issue. I wonder if this can be solved by using some sort of MD
plugin for Confluence or something, so the docs can be visible on ASF cwiki
site?
Cos
Re: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 04.03.2015 23:41, Branko Čibej wrote:
> On 04.03.2015 23:33, Konstantin Boudnik wrote:
>> On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
>>> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
>>>
>>>> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
>>>>> readme.io is a very cool documentation platform which gives free web
>>>>> hosting, versioning, and sexy looks to open source projects, including
>>>>> Apache projects. It stores documentation in a regular markdown format,
>>>> and
>>>>> I will add the MD files to the GIT tree before doing the next release.
>>>> This
>>>>> way readme.io will be the copy of the documentation stored in github. I
>>>> You meant 'stored in Apache git", didn't you?
>>>>
>>> Yes, the Apache git.
>> It seems to be satisfactory solutio as far as we keep the original docs source
>> in Apache, no?
>
> There are a couple open questions here:
>
> * While all committers can update the docs, all committers should
> also be able to manage the readme.io site. AFAIK there's no
> automated way to achieve that, and no documented way for adding
> site administrators. That's kind of a bad start.
> * Readme.io is the /only/ online source of the docs, apparently. The
> Incubator site links there, and there's no other way to see the
> docs short of checking out the source. So ... what if readme.io
> goes away?
>
That's beside the fact that "Fork me on GitHub" is really a very bad
suggestion. It's better to get people involved on the dev@ (and later
users@) lists than to encourage them to throw-and-forget patches at the
project through GitHub pull requests (which are, frankly, one of the
more onerous ways for contributing to a project).
-- Brane
Re: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 04.03.2015 23:33, Konstantin Boudnik wrote:
> On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
>> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
>>
>>> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
>>>> readme.io is a very cool documentation platform which gives free web
>>>> hosting, versioning, and sexy looks to open source projects, including
>>>> Apache projects. It stores documentation in a regular markdown format,
>>> and
>>>> I will add the MD files to the GIT tree before doing the next release.
>>> This
>>>> way readme.io will be the copy of the documentation stored in github. I
>>> You meant 'stored in Apache git", didn't you?
>>>
>> Yes, the Apache git.
> It seems to be satisfactory solutio as far as we keep the original docs source
> in Apache, no?
There are a couple open questions here:
* While all committers can update the docs, all committers should also
be able to manage the readme.io site. AFAIK there's no automated way
to achieve that, and no documented way for adding site
administrators. That's kind of a bad start.
* Readme.io is the /only/ online source of the docs, apparently. The
Incubator site links there, and there's no other way to see the docs
short of checking out the source. So ... what if readme.io goes away?
-- Brane
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
On Wed, Mar 04, 2015 at 02:22PM, Dmitriy Setrakyan wrote:
> On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
>
> > On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
> > > readme.io is a very cool documentation platform which gives free web
> > > hosting, versioning, and sexy looks to open source projects, including
> > > Apache projects. It stores documentation in a regular markdown format,
> > and
> > > I will add the MD files to the GIT tree before doing the next release.
> > This
> > > way readme.io will be the copy of the documentation stored in github. I
> >
> > You meant 'stored in Apache git", didn't you?
> >
>
> Yes, the Apache git.
It seems to be satisfactory solutio as far as we keep the original docs source
in Apache, no?
> > > think we are compliant with Apache policies here.
> > >
> > > All Ignite committers have access to update the documentation. On top of
> > > that, the community can make suggestions to update any of the pages
> > through
> > > a very cool "Suggest Edits" feature in readme.io.
> > >
> > > Let me know if you have more questions.
> > >
> > > D.
> > >
> > >
> > > On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
> > > wrote:
> > >
> > > > I am not sure how readme.io works but technically the actual content
> > > > should be hosted in apache domain.
> > > >
> > > > This is similar to our github repo which is merely mirror to Apache git
> > > > repo.
> > > >
> > > > The question is who has access to update readme.io for ignite and it
> > > > must be just mirror or copy from document content hosted somewhere
> > > > under Apache domain.
> > > >
> > > > On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> > > > <ds...@apache.org> wrote:
> > > > > Hello Igniters,
> > > > >
> > > > > I think I have found a pretty cool home for our documentation:
> > > > > http://apacheignite.readme.io/v1.0/docs
> > > > >
> > > > > https://readme.io is nice enough to host open source documentation
> > for
> > > > > free, and I like the editability and friendliness of their UI.
> > > > >
> > > > > I have added most of the committers as admins to the documentation
> > wiki.
> > > > >
> > > > > Feel free to start contributing pages.
> > > > >
> > > > > D.
> > > >
> >
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Wed, Mar 4, 2015 at 2:20 PM, Konstantin Boudnik <co...@apache.org> wrote:
> On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
> > readme.io is a very cool documentation platform which gives free web
> > hosting, versioning, and sexy looks to open source projects, including
> > Apache projects. It stores documentation in a regular markdown format,
> and
> > I will add the MD files to the GIT tree before doing the next release.
> This
> > way readme.io will be the copy of the documentation stored in github. I
>
> You meant 'stored in Apache git", didn't you?
>
Yes, the Apache git.
>
> > think we are compliant with Apache policies here.
> >
> > All Ignite committers have access to update the documentation. On top of
> > that, the community can make suggestions to update any of the pages
> through
> > a very cool "Suggest Edits" feature in readme.io.
> >
> > Let me know if you have more questions.
> >
> > D.
> >
> >
> > On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
> > wrote:
> >
> > > I am not sure how readme.io works but technically the actual content
> > > should be hosted in apache domain.
> > >
> > > This is similar to our github repo which is merely mirror to Apache git
> > > repo.
> > >
> > > The question is who has access to update readme.io for ignite and it
> > > must be just mirror or copy from document content hosted somewhere
> > > under Apache domain.
> > >
> > > On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> > > <ds...@apache.org> wrote:
> > > > Hello Igniters,
> > > >
> > > > I think I have found a pretty cool home for our documentation:
> > > > http://apacheignite.readme.io/v1.0/docs
> > > >
> > > > https://readme.io is nice enough to host open source documentation
> for
> > > > free, and I like the editability and friendliness of their UI.
> > > >
> > > > I have added most of the committers as admins to the documentation
> wiki.
> > > >
> > > > Feel free to start contributing pages.
> > > >
> > > > D.
> > >
>
Re: New home for Ignite documentation
Posted by Konstantin Boudnik <co...@apache.org>.
On Wed, Mar 04, 2015 at 02:18PM, Dmitriy Setrakyan wrote:
> readme.io is a very cool documentation platform which gives free web
> hosting, versioning, and sexy looks to open source projects, including
> Apache projects. It stores documentation in a regular markdown format, and
> I will add the MD files to the GIT tree before doing the next release. This
> way readme.io will be the copy of the documentation stored in github. I
You meant 'stored in Apache git", didn't you?
> think we are compliant with Apache policies here.
>
> All Ignite committers have access to update the documentation. On top of
> that, the community can make suggestions to update any of the pages through
> a very cool "Suggest Edits" feature in readme.io.
>
> Let me know if you have more questions.
>
> D.
>
>
> On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
> wrote:
>
> > I am not sure how readme.io works but technically the actual content
> > should be hosted in apache domain.
> >
> > This is similar to our github repo which is merely mirror to Apache git
> > repo.
> >
> > The question is who has access to update readme.io for ignite and it
> > must be just mirror or copy from document content hosted somewhere
> > under Apache domain.
> >
> > On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> > <ds...@apache.org> wrote:
> > > Hello Igniters,
> > >
> > > I think I have found a pretty cool home for our documentation:
> > > http://apacheignite.readme.io/v1.0/docs
> > >
> > > https://readme.io is nice enough to host open source documentation for
> > > free, and I like the editability and friendliness of their UI.
> > >
> > > I have added most of the committers as admins to the documentation wiki.
> > >
> > > Feel free to start contributing pages.
> > >
> > > D.
> >
Re: Fwd: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 11.03.2015 08:58, Dmitriy Setrakyan wrote:
> On Tue, Mar 10, 2015 at 10:20 PM, Branko Čibej <br...@apache.org> wrote:
>
>
>>> On top of that, everyone in the
>>> community has a chance to suggest edits to any piece of the documentation
>>> via "Suggest Edits" link on every page (yet another cool feature provided
>>> by readme.io).
>>>
>>> However, I believe we have to live with creating documentation in
>> readme.io
>>> first and then exporting it to GIT. I have also created a script which
>>> automatically goes through all MD files in the documentation and adds
>>> Apache License to it.
>> Can you write an automated script that proves that every change in the
>> documentation was made by an Ignite committer? Because that's what all
>> this boils down to: having a verifiable audit trail for every line of
>> source or documentation in a release. This is fundamental to the legal
>> requirements for a release. This is also the reason why the ASF insists
>> that repositories must be hosted on our infrastructure.
>>
> There is plenty of documentation in Apache TLPs which is being hosted in
> Atlasssian Confluence as well (https://cwiki.apache.org/). I assure you
> that in those cases Confluence is the primary editor of that documentation,
> and that it never ends up directly in the source tree. Can you explain why
> that process is any better than the one we have setup?
The difference is in the *.apache.org vs. *.io.
As I said, hosting this externally (pasting from repo isn't the same as
generating) doesn't feel right to me, but I'm not sure if it actually
violates any policies.
You have to understand that I'm not being pedantic for the sake of
making your life miserable, although I can quite understand if you're
feeling that way lately. :) I'm all for making things as simple as
possible for developers and users. But as I said elsewhere, the policies
aren't arbitrary.
-- Brane
Fwd: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
On Tue, Mar 10, 2015 at 10:20 PM, Branko Čibej <br...@apache.org> wrote:
> On 08.03.2015 08:37, Dmitriy Setrakyan wrote:
> > I agree about most points, and we are addressing them.
> >
> > I still want to say however, that there is nothing proprietary about
> > keeping documentation hosted on readme.io. Apache Ignite is a fairly
> > feature rich project, and we had to pick a tool that would not only
> produce
> > documentation for us, but would also allow us to quickly add the
> > documentation, quickly review it and publish it. Simply keeping MD files
> in
> > the source tree requires lengthy customizations to CSS as well as writing
> > documentation in a human unreadable format. Readme.io actually agreed to
> > give us free hosing and allowed us to use their cool software for free.
> It
> > would be a huge loss of productivity for us to abandon it.
>
> Let me see if I understand this: readme.io is the only place where you
> can edit the documentation. You cannot, currently, edit the markdown
> with a text editor, commit it, then upload it to readme.io. In other
> words, the repository is not the source of the documentation.
>
You can, if you like, make edits in markdown document directly and then
paste them into readme.io.
>
> > Having said that, I have added the following:
> > - Apache License: http://apacheignite.readme.io/v1.0/docs/license
> > - ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
> >
> > I have also exported the documentation to our GIT source tree:
> >
> https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
> >
> > All committers have account in readme.io.
>
> I don't. And I find no documented procedure on the Ignite web site or
> elsewhere that would remind people to give new committers access to
> readme.io.
>
You do now (see my other email)
>
> > On top of that, everyone in the
> > community has a chance to suggest edits to any piece of the documentation
> > via "Suggest Edits" link on every page (yet another cool feature provided
> > by readme.io).
> >
> > However, I believe we have to live with creating documentation in
> readme.io
> > first and then exporting it to GIT. I have also created a script which
> > automatically goes through all MD files in the documentation and adds
> > Apache License to it.
>
> Can you write an automated script that proves that every change in the
> documentation was made by an Ignite committer? Because that's what all
> this boils down to: having a verifiable audit trail for every line of
> source or documentation in a release. This is fundamental to the legal
> requirements for a release. This is also the reason why the ASF insists
> that repositories must be hosted on our infrastructure.
>
There is plenty of documentation in Apache TLPs which is being hosted in
Atlasssian Confluence as well (https://cwiki.apache.org/). I assure you
that in those cases Confluence is the primary editor of that documentation,
and that it never ends up directly in the source tree. Can you explain why
that process is any better than the one we have setup?
Having said that, we still can setup a process which ensures that after any
committer makes any changes in readme.io, they export them to GIT and
commit them. This way the trail will be there. It is a soft contract, but
nevertheless, committers can follow it. We community agrees, I will
document this process, ironically, on readme.io :)
Lastly, I think we should be viewing readme.io as a productivity tool, much
the same as IDEA or Eclipse for java development. It's a pleasure to work
with readme.io, and is a huge productivity boost compared to raw text
editing. I would not try to fight it, but instead suggest any changes we
have to make to the process (if any at all), so we can continue using it.
> I believe that the scheme you set up with readme.io does not conform to
> these requirements, but I'm not sure. We should ask on legal-discuss@. I
> haven't come across an ASF project yet that doesn't generate
> documentation from source in its repository; it feels wrong to me.
> -- Brane
>
> > On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <he...@gmail.com>
> > wrote:
> >
> >> The key is that the changes have to happen in the Apache Git before
> >> copied to other location.
> >>
> >> Please do send the access information for Ignite readme.io to private@
> >> list to make sure all committers have access.
> >>
> >> - Henry
> >>
> >> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <
> dsetrakyan@apache.org>
> >> wrote:
> >>> readme.io is a very cool documentation platform which gives free web
> >>> hosting, versioning, and sexy looks to open source projects, including
> >>> Apache projects. It stores documentation in a regular markdown format,
> >> and
> >>> I will add the MD files to the GIT tree before doing the next release.
> >> This
> >>> way readme.io will be the copy of the documentation stored in github.
> I
> >>> think we are compliant with Apache policies here.
> >>>
> >>> All Ignite committers have access to update the documentation. On top
> of
> >>> that, the community can make suggestions to update any of the pages
> >> through
> >>> a very cool "Suggest Edits" feature in readme.io.
> >>>
> >>> Let me know if you have more questions.
> >>>
> >>> D.
> >>>
> >>>
> >>> On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <henry.saputra@gmail.com
> >
> >>> wrote:
> >>>
> >>>> I am not sure how readme.io works but technically the actual content
> >>>> should be hosted in apache domain.
> >>>>
> >>>> This is similar to our github repo which is merely mirror to Apache
> git
> >>>> repo.
> >>>>
> >>>> The question is who has access to update readme.io for ignite and it
> >>>> must be just mirror or copy from document content hosted somewhere
> >>>> under Apache domain.
> >>>>
> >>>> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> >>>> <ds...@apache.org> wrote:
> >>>>> Hello Igniters,
> >>>>>
> >>>>> I think I have found a pretty cool home for our documentation:
> >>>>> http://apacheignite.readme.io/v1.0/docs
> >>>>>
> >>>>> https://readme.io is nice enough to host open source documentation
> >> for
> >>>>> free, and I like the editability and friendliness of their UI.
> >>>>>
> >>>>> I have added most of the committers as admins to the documentation
> >> wiki.
> >>>>> Feel free to start contributing pages.
> >>>>>
> >>>>> D.
>
>
Re: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 08.03.2015 08:37, Dmitriy Setrakyan wrote:
> I agree about most points, and we are addressing them.
>
> I still want to say however, that there is nothing proprietary about
> keeping documentation hosted on readme.io. Apache Ignite is a fairly
> feature rich project, and we had to pick a tool that would not only produce
> documentation for us, but would also allow us to quickly add the
> documentation, quickly review it and publish it. Simply keeping MD files in
> the source tree requires lengthy customizations to CSS as well as writing
> documentation in a human unreadable format. Readme.io actually agreed to
> give us free hosing and allowed us to use their cool software for free. It
> would be a huge loss of productivity for us to abandon it.
Let me see if I understand this: readme.io is the only place where you
can edit the documentation. You cannot, currently, edit the markdown
with a text editor, commit it, then upload it to readme.io. In other
words, the repository is not the source of the documentation.
> Having said that, I have added the following:
> - Apache License: http://apacheignite.readme.io/v1.0/docs/license
> - ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
>
> I have also exported the documentation to our GIT source tree:
> https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
>
> All committers have account in readme.io.
I don't. And I find no documented procedure on the Ignite web site or
elsewhere that would remind people to give new committers access to
readme.io.
> On top of that, everyone in the
> community has a chance to suggest edits to any piece of the documentation
> via "Suggest Edits" link on every page (yet another cool feature provided
> by readme.io).
>
> However, I believe we have to live with creating documentation in readme.io
> first and then exporting it to GIT. I have also created a script which
> automatically goes through all MD files in the documentation and adds
> Apache License to it.
Can you write an automated script that proves that every change in the
documentation was made by an Ignite committer? Because that's what all
this boils down to: having a verifiable audit trail for every line of
source or documentation in a release. This is fundamental to the legal
requirements for a release. This is also the reason why the ASF insists
that repositories must be hosted on our infrastructure.
I believe that the scheme you set up with readme.io does not conform to
these requirements, but I'm not sure. We should ask on legal-discuss@. I
haven't come across an ASF project yet that doesn't generate
documentation from source in its repository; it feels wrong to me.
-- Brane
> On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <he...@gmail.com>
> wrote:
>
>> The key is that the changes have to happen in the Apache Git before
>> copied to other location.
>>
>> Please do send the access information for Ignite readme.io to private@
>> list to make sure all committers have access.
>>
>> - Henry
>>
>> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <ds...@apache.org>
>> wrote:
>>> readme.io is a very cool documentation platform which gives free web
>>> hosting, versioning, and sexy looks to open source projects, including
>>> Apache projects. It stores documentation in a regular markdown format,
>> and
>>> I will add the MD files to the GIT tree before doing the next release.
>> This
>>> way readme.io will be the copy of the documentation stored in github. I
>>> think we are compliant with Apache policies here.
>>>
>>> All Ignite committers have access to update the documentation. On top of
>>> that, the community can make suggestions to update any of the pages
>> through
>>> a very cool "Suggest Edits" feature in readme.io.
>>>
>>> Let me know if you have more questions.
>>>
>>> D.
>>>
>>>
>>> On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
>>> wrote:
>>>
>>>> I am not sure how readme.io works but technically the actual content
>>>> should be hosted in apache domain.
>>>>
>>>> This is similar to our github repo which is merely mirror to Apache git
>>>> repo.
>>>>
>>>> The question is who has access to update readme.io for ignite and it
>>>> must be just mirror or copy from document content hosted somewhere
>>>> under Apache domain.
>>>>
>>>> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
>>>> <ds...@apache.org> wrote:
>>>>> Hello Igniters,
>>>>>
>>>>> I think I have found a pretty cool home for our documentation:
>>>>> http://apacheignite.readme.io/v1.0/docs
>>>>>
>>>>> https://readme.io is nice enough to host open source documentation
>> for
>>>>> free, and I like the editability and friendliness of their UI.
>>>>>
>>>>> I have added most of the committers as admins to the documentation
>> wiki.
>>>>> Feel free to start contributing pages.
>>>>>
>>>>> D.
Re: New home for Ignite documentation
Posted by Branko Čibej <br...@apache.org>.
On 13.03.2015 01:17, Dmitriy Setrakyan wrote:
> Roman,
>
> Unfortunately we are forced at this point to take the same path as DataStax
> with planetcassandra.org (granted, of course, that community agrees). Here
> are the main reasons:
>
> 1. We have already invested over a month of very hard and scrupulous labor
> on producing documentation in readme.io and simply do not have another
> month to do it in another tool. (I have sent out my first email about
> readme.io on Feb 9 and unfortunately got feedback about it not being
> genuine from ASF standpoint only a month later)
I wonder what's the rush here. You don't have a deadline, neither for
publishing the docs nor for graduating from the Incubator.
> 2. Readme.io gives a huge productivity boost for creating documentation by
> providing various CSS templates, versioning, wysiwyg editor, and community
> forum. I am not aware of any Markdown tool with such capabilities, and even
> if we find one, we probably would spend another month editing CSS just to
> make it look as pretty.
>
> I appreciate everyone's feedback on this. If there are no objections, I
> will start editing documentation to make sure that it has proper use of
> Apache trademarks and attributions.
>
> D.
>
> On Wed, Mar 11, 2015 at 10:58 AM, Roman Shaposhnik <ro...@shaposhnik.org>
> wrote:
>
>> On Wed, Mar 11, 2015 at 9:54 AM, Dmitriy Setrakyan
>> <ds...@apache.org> wrote:
>>> I understand that no-one is trying to make things harder, but at the same
>>> time, I mostly hear "DON'T DO THIS" and "DON'T DO THAT". What I would
>>> appreciate is if we all tried to come up with a way to keep docs in
>>> readme.io (especially given that many within community sweated for the
>> past
>>> month on adding documentation to readme.io).
>>>
>>> I have several questions:
>>>
>>> 1. Is this technicality about which tool is used to create
>> documentation
>>> documented somewhere? I cannot find anything. I treat readme.io as a
>>> tool for creating documentation which I then add to GIT.
>> It is about where the canonical source of truth is. You *have* to have it
>> at *.apache.org. You're more than welcome to have mirrors all over
>> the place, of course.
>>
>> There's also a matter of fostering the community by lowering the barrier
>> of entry. As a developer on the project I would really appreciate if
>> changing documentation followed the same process as changing code.
>> This is not a hard requirement, but it really helps. I don't want yet
>> another
>> process. I want to be able to commit to the same repo.
>>
>>> 2. Are 3rd parties allowed to provide documentation for Apache
>> Projects
>>> (cannot imagine why not or how we can stop them)? If so, we can
>> maintain
>>> this documentation as provided by 3rd party and treat Javadoc, which
>> is
>>> part of the source code, as the primary source documentation for
>> Apache
>>> Ignite. Also, all pages important to the community, like "Get
>> Involved" for
>>> example, will be kept directly on the Ignite website.
>> You can, of course, splinter your documentation. Case in point:
>> http://planetcassandra.org/
>> which is operated by DataStax folks. However, as a general recommendation
>> I will really encourage you NOT to do so for core project.
>>
>> Thanks,
>> Roman.
>>
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
Roman,
Unfortunately we are forced at this point to take the same path as DataStax
with planetcassandra.org (granted, of course, that community agrees). Here
are the main reasons:
1. We have already invested over a month of very hard and scrupulous labor
on producing documentation in readme.io and simply do not have another
month to do it in another tool. (I have sent out my first email about
readme.io on Feb 9 and unfortunately got feedback about it not being
genuine from ASF standpoint only a month later)
2. Readme.io gives a huge productivity boost for creating documentation by
providing various CSS templates, versioning, wysiwyg editor, and community
forum. I am not aware of any Markdown tool with such capabilities, and even
if we find one, we probably would spend another month editing CSS just to
make it look as pretty.
I appreciate everyone's feedback on this. If there are no objections, I
will start editing documentation to make sure that it has proper use of
Apache trademarks and attributions.
D.
On Wed, Mar 11, 2015 at 10:58 AM, Roman Shaposhnik <ro...@shaposhnik.org>
wrote:
> On Wed, Mar 11, 2015 at 9:54 AM, Dmitriy Setrakyan
> <ds...@apache.org> wrote:
> > I understand that no-one is trying to make things harder, but at the same
> > time, I mostly hear "DON'T DO THIS" and "DON'T DO THAT". What I would
> > appreciate is if we all tried to come up with a way to keep docs in
> > readme.io (especially given that many within community sweated for the
> past
> > month on adding documentation to readme.io).
> >
> > I have several questions:
> >
> > 1. Is this technicality about which tool is used to create
> documentation
> > documented somewhere? I cannot find anything. I treat readme.io as a
> > tool for creating documentation which I then add to GIT.
>
> It is about where the canonical source of truth is. You *have* to have it
> at *.apache.org. You're more than welcome to have mirrors all over
> the place, of course.
>
> There's also a matter of fostering the community by lowering the barrier
> of entry. As a developer on the project I would really appreciate if
> changing documentation followed the same process as changing code.
> This is not a hard requirement, but it really helps. I don't want yet
> another
> process. I want to be able to commit to the same repo.
>
> > 2. Are 3rd parties allowed to provide documentation for Apache
> Projects
> > (cannot imagine why not or how we can stop them)? If so, we can
> maintain
> > this documentation as provided by 3rd party and treat Javadoc, which
> is
> > part of the source code, as the primary source documentation for
> Apache
> > Ignite. Also, all pages important to the community, like "Get
> Involved" for
> > example, will be kept directly on the Ignite website.
>
> You can, of course, splinter your documentation. Case in point:
> http://planetcassandra.org/
> which is operated by DataStax folks. However, as a general recommendation
> I will really encourage you NOT to do so for core project.
>
> Thanks,
> Roman.
>
Re: New home for Ignite documentation
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Wed, Mar 11, 2015 at 9:54 AM, Dmitriy Setrakyan
<ds...@apache.org> wrote:
> I understand that no-one is trying to make things harder, but at the same
> time, I mostly hear "DON'T DO THIS" and "DON'T DO THAT". What I would
> appreciate is if we all tried to come up with a way to keep docs in
> readme.io (especially given that many within community sweated for the past
> month on adding documentation to readme.io).
>
> I have several questions:
>
> 1. Is this technicality about which tool is used to create documentation
> documented somewhere? I cannot find anything. I treat readme.io as a
> tool for creating documentation which I then add to GIT.
It is about where the canonical source of truth is. You *have* to have it
at *.apache.org. You're more than welcome to have mirrors all over
the place, of course.
There's also a matter of fostering the community by lowering the barrier
of entry. As a developer on the project I would really appreciate if
changing documentation followed the same process as changing code.
This is not a hard requirement, but it really helps. I don't want yet another
process. I want to be able to commit to the same repo.
> 2. Are 3rd parties allowed to provide documentation for Apache Projects
> (cannot imagine why not or how we can stop them)? If so, we can maintain
> this documentation as provided by 3rd party and treat Javadoc, which is
> part of the source code, as the primary source documentation for Apache
> Ignite. Also, all pages important to the community, like "Get Involved" for
> example, will be kept directly on the Ignite website.
You can, of course, splinter your documentation. Case in point:
http://planetcassandra.org/
which is operated by DataStax folks. However, as a general recommendation
I will really encourage you NOT to do so for core project.
Thanks,
Roman.
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
I understand that no-one is trying to make things harder, but at the same
time, I mostly hear "DON'T DO THIS" and "DON'T DO THAT". What I would
appreciate is if we all tried to come up with a way to keep docs in
readme.io (especially given that many within community sweated for the past
month on adding documentation to readme.io).
I have several questions:
1. Is this technicality about which tool is used to create documentation
documented somewhere? I cannot find anything. I treat readme.io as a
tool for creating documentation which I then add to GIT.
2. Are 3rd parties allowed to provide documentation for Apache Projects
(cannot imagine why not or how we can stop them)? If so, we can maintain
this documentation as provided by 3rd party and treat Javadoc, which is
part of the source code, as the primary source documentation for Apache
Ignite. Also, all pages important to the community, like "Get Involved" for
example, will be kept directly on the Ignite website.
D.
On Wed, Mar 11, 2015 at 7:53 AM, Henry Saputra <he...@gmail.com>
wrote:
> Dmitriy,
>
> The main key point is that source of truth of documentation should be
> in *.apache.org domain.
>
> Like Brane had said we are not here to make it harder for new podling
> but these are some transition stuff need to be done.
>
> If Ignite wants to use readme.io then it has to be mirror or copy of
> files reside in apache.org domain, and not the other way.
>
> - Henry
>
> On Sat, Mar 7, 2015 at 11:37 PM, Dmitriy Setrakyan
> <ds...@apache.org> wrote:
> > I agree about most points, and we are addressing them.
> >
> > I still want to say however, that there is nothing proprietary about
> > keeping documentation hosted on readme.io. Apache Ignite is a fairly
> > feature rich project, and we had to pick a tool that would not only
> produce
> > documentation for us, but would also allow us to quickly add the
> > documentation, quickly review it and publish it. Simply keeping MD files
> in
> > the source tree requires lengthy customizations to CSS as well as writing
> > documentation in a human unreadable format. Readme.io actually agreed to
> > give us free hosing and allowed us to use their cool software for free.
> It
> > would be a huge loss of productivity for us to abandon it.
> >
> > Having said that, I have added the following:
> > - Apache License: http://apacheignite.readme.io/v1.0/docs/license
> > - ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
> >
> > I have also exported the documentation to our GIT source tree:
> >
> https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
> >
> > All committers have account in readme.io. On top of that, everyone in
> the
> > community has a chance to suggest edits to any piece of the documentation
> > via "Suggest Edits" link on every page (yet another cool feature provided
> > by readme.io).
> >
> > However, I believe we have to live with creating documentation in
> readme.io
> > first and then exporting it to GIT. I have also created a script which
> > automatically goes through all MD files in the documentation and adds
> > Apache License to it.
> >
> > D.
> >
> >
> >
> > On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <he...@gmail.com>
> > wrote:
> >
> >> The key is that the changes have to happen in the Apache Git before
> >> copied to other location.
> >>
> >> Please do send the access information for Ignite readme.io to private@
> >> list to make sure all committers have access.
> >>
> >> - Henry
> >>
> >> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <
> dsetrakyan@apache.org>
> >> wrote:
> >> > readme.io is a very cool documentation platform which gives free web
> >> > hosting, versioning, and sexy looks to open source projects, including
> >> > Apache projects. It stores documentation in a regular markdown format,
> >> and
> >> > I will add the MD files to the GIT tree before doing the next release.
> >> This
> >> > way readme.io will be the copy of the documentation stored in
> github. I
> >> > think we are compliant with Apache policies here.
> >> >
> >> > All Ignite committers have access to update the documentation. On top
> of
> >> > that, the community can make suggestions to update any of the pages
> >> through
> >> > a very cool "Suggest Edits" feature in readme.io.
> >> >
> >> > Let me know if you have more questions.
> >> >
> >> > D.
> >> >
> >> >
> >> > On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <
> henry.saputra@gmail.com>
> >> > wrote:
> >> >
> >> >> I am not sure how readme.io works but technically the actual content
> >> >> should be hosted in apache domain.
> >> >>
> >> >> This is similar to our github repo which is merely mirror to Apache
> git
> >> >> repo.
> >> >>
> >> >> The question is who has access to update readme.io for ignite and it
> >> >> must be just mirror or copy from document content hosted somewhere
> >> >> under Apache domain.
> >> >>
> >> >> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> >> >> <ds...@apache.org> wrote:
> >> >> > Hello Igniters,
> >> >> >
> >> >> > I think I have found a pretty cool home for our documentation:
> >> >> > http://apacheignite.readme.io/v1.0/docs
> >> >> >
> >> >> > https://readme.io is nice enough to host open source documentation
> >> for
> >> >> > free, and I like the editability and friendliness of their UI.
> >> >> >
> >> >> > I have added most of the committers as admins to the documentation
> >> wiki.
> >> >> >
> >> >> > Feel free to start contributing pages.
> >> >> >
> >> >> > D.
> >> >>
> >>
>
Re: New home for Ignite documentation
Posted by Henry Saputra <he...@gmail.com>.
Dmitriy,
The main key point is that source of truth of documentation should be
in *.apache.org domain.
Like Brane had said we are not here to make it harder for new podling
but these are some transition stuff need to be done.
If Ignite wants to use readme.io then it has to be mirror or copy of
files reside in apache.org domain, and not the other way.
- Henry
On Sat, Mar 7, 2015 at 11:37 PM, Dmitriy Setrakyan
<ds...@apache.org> wrote:
> I agree about most points, and we are addressing them.
>
> I still want to say however, that there is nothing proprietary about
> keeping documentation hosted on readme.io. Apache Ignite is a fairly
> feature rich project, and we had to pick a tool that would not only produce
> documentation for us, but would also allow us to quickly add the
> documentation, quickly review it and publish it. Simply keeping MD files in
> the source tree requires lengthy customizations to CSS as well as writing
> documentation in a human unreadable format. Readme.io actually agreed to
> give us free hosing and allowed us to use their cool software for free. It
> would be a huge loss of productivity for us to abandon it.
>
> Having said that, I have added the following:
> - Apache License: http://apacheignite.readme.io/v1.0/docs/license
> - ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
>
> I have also exported the documentation to our GIT source tree:
> https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
>
> All committers have account in readme.io. On top of that, everyone in the
> community has a chance to suggest edits to any piece of the documentation
> via "Suggest Edits" link on every page (yet another cool feature provided
> by readme.io).
>
> However, I believe we have to live with creating documentation in readme.io
> first and then exporting it to GIT. I have also created a script which
> automatically goes through all MD files in the documentation and adds
> Apache License to it.
>
> D.
>
>
>
> On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <he...@gmail.com>
> wrote:
>
>> The key is that the changes have to happen in the Apache Git before
>> copied to other location.
>>
>> Please do send the access information for Ignite readme.io to private@
>> list to make sure all committers have access.
>>
>> - Henry
>>
>> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <ds...@apache.org>
>> wrote:
>> > readme.io is a very cool documentation platform which gives free web
>> > hosting, versioning, and sexy looks to open source projects, including
>> > Apache projects. It stores documentation in a regular markdown format,
>> and
>> > I will add the MD files to the GIT tree before doing the next release.
>> This
>> > way readme.io will be the copy of the documentation stored in github. I
>> > think we are compliant with Apache policies here.
>> >
>> > All Ignite committers have access to update the documentation. On top of
>> > that, the community can make suggestions to update any of the pages
>> through
>> > a very cool "Suggest Edits" feature in readme.io.
>> >
>> > Let me know if you have more questions.
>> >
>> > D.
>> >
>> >
>> > On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
>> > wrote:
>> >
>> >> I am not sure how readme.io works but technically the actual content
>> >> should be hosted in apache domain.
>> >>
>> >> This is similar to our github repo which is merely mirror to Apache git
>> >> repo.
>> >>
>> >> The question is who has access to update readme.io for ignite and it
>> >> must be just mirror or copy from document content hosted somewhere
>> >> under Apache domain.
>> >>
>> >> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
>> >> <ds...@apache.org> wrote:
>> >> > Hello Igniters,
>> >> >
>> >> > I think I have found a pretty cool home for our documentation:
>> >> > http://apacheignite.readme.io/v1.0/docs
>> >> >
>> >> > https://readme.io is nice enough to host open source documentation
>> for
>> >> > free, and I like the editability and friendliness of their UI.
>> >> >
>> >> > I have added most of the committers as admins to the documentation
>> wiki.
>> >> >
>> >> > Feel free to start contributing pages.
>> >> >
>> >> > D.
>> >>
>>
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
I agree about most points, and we are addressing them.
I still want to say however, that there is nothing proprietary about
keeping documentation hosted on readme.io. Apache Ignite is a fairly
feature rich project, and we had to pick a tool that would not only produce
documentation for us, but would also allow us to quickly add the
documentation, quickly review it and publish it. Simply keeping MD files in
the source tree requires lengthy customizations to CSS as well as writing
documentation in a human unreadable format. Readme.io actually agreed to
give us free hosing and allowed us to use their cool software for free. It
would be a huge loss of productivity for us to abandon it.
Having said that, I have added the following:
- Apache License: http://apacheignite.readme.io/v1.0/docs/license
- ASF Copyright: http://apacheignite.readme.io/v1.0/docs/copyright
I have also exported the documentation to our GIT source tree:
https://git-wip-us.apache.org/repos/asf?p=incubator-ignite.git;a=tree;f=wiki;hb=refs/heads/sprint-2
All committers have account in readme.io. On top of that, everyone in the
community has a chance to suggest edits to any piece of the documentation
via "Suggest Edits" link on every page (yet another cool feature provided
by readme.io).
However, I believe we have to live with creating documentation in readme.io
first and then exporting it to GIT. I have also created a script which
automatically goes through all MD files in the documentation and adds
Apache License to it.
D.
On Thu, Mar 5, 2015 at 3:31 PM, Henry Saputra <he...@gmail.com>
wrote:
> The key is that the changes have to happen in the Apache Git before
> copied to other location.
>
> Please do send the access information for Ignite readme.io to private@
> list to make sure all committers have access.
>
> - Henry
>
> On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <ds...@apache.org>
> wrote:
> > readme.io is a very cool documentation platform which gives free web
> > hosting, versioning, and sexy looks to open source projects, including
> > Apache projects. It stores documentation in a regular markdown format,
> and
> > I will add the MD files to the GIT tree before doing the next release.
> This
> > way readme.io will be the copy of the documentation stored in github. I
> > think we are compliant with Apache policies here.
> >
> > All Ignite committers have access to update the documentation. On top of
> > that, the community can make suggestions to update any of the pages
> through
> > a very cool "Suggest Edits" feature in readme.io.
> >
> > Let me know if you have more questions.
> >
> > D.
> >
> >
> > On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
> > wrote:
> >
> >> I am not sure how readme.io works but technically the actual content
> >> should be hosted in apache domain.
> >>
> >> This is similar to our github repo which is merely mirror to Apache git
> >> repo.
> >>
> >> The question is who has access to update readme.io for ignite and it
> >> must be just mirror or copy from document content hosted somewhere
> >> under Apache domain.
> >>
> >> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> >> <ds...@apache.org> wrote:
> >> > Hello Igniters,
> >> >
> >> > I think I have found a pretty cool home for our documentation:
> >> > http://apacheignite.readme.io/v1.0/docs
> >> >
> >> > https://readme.io is nice enough to host open source documentation
> for
> >> > free, and I like the editability and friendliness of their UI.
> >> >
> >> > I have added most of the committers as admins to the documentation
> wiki.
> >> >
> >> > Feel free to start contributing pages.
> >> >
> >> > D.
> >>
>
Re: New home for Ignite documentation
Posted by Henry Saputra <he...@gmail.com>.
The key is that the changes have to happen in the Apache Git before
copied to other location.
Please do send the access information for Ignite readme.io to private@
list to make sure all committers have access.
- Henry
On Wed, Mar 4, 2015 at 2:18 PM, Dmitriy Setrakyan <ds...@apache.org> wrote:
> readme.io is a very cool documentation platform which gives free web
> hosting, versioning, and sexy looks to open source projects, including
> Apache projects. It stores documentation in a regular markdown format, and
> I will add the MD files to the GIT tree before doing the next release. This
> way readme.io will be the copy of the documentation stored in github. I
> think we are compliant with Apache policies here.
>
> All Ignite committers have access to update the documentation. On top of
> that, the community can make suggestions to update any of the pages through
> a very cool "Suggest Edits" feature in readme.io.
>
> Let me know if you have more questions.
>
> D.
>
>
> On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
> wrote:
>
>> I am not sure how readme.io works but technically the actual content
>> should be hosted in apache domain.
>>
>> This is similar to our github repo which is merely mirror to Apache git
>> repo.
>>
>> The question is who has access to update readme.io for ignite and it
>> must be just mirror or copy from document content hosted somewhere
>> under Apache domain.
>>
>> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
>> <ds...@apache.org> wrote:
>> > Hello Igniters,
>> >
>> > I think I have found a pretty cool home for our documentation:
>> > http://apacheignite.readme.io/v1.0/docs
>> >
>> > https://readme.io is nice enough to host open source documentation for
>> > free, and I like the editability and friendliness of their UI.
>> >
>> > I have added most of the committers as admins to the documentation wiki.
>> >
>> > Feel free to start contributing pages.
>> >
>> > D.
>>
Re: New home for Ignite documentation
Posted by Dmitriy Setrakyan <ds...@apache.org>.
readme.io is a very cool documentation platform which gives free web
hosting, versioning, and sexy looks to open source projects, including
Apache projects. It stores documentation in a regular markdown format, and
I will add the MD files to the GIT tree before doing the next release. This
way readme.io will be the copy of the documentation stored in github. I
think we are compliant with Apache policies here.
All Ignite committers have access to update the documentation. On top of
that, the community can make suggestions to update any of the pages through
a very cool "Suggest Edits" feature in readme.io.
Let me know if you have more questions.
D.
On Wed, Mar 4, 2015 at 1:43 PM, Henry Saputra <he...@gmail.com>
wrote:
> I am not sure how readme.io works but technically the actual content
> should be hosted in apache domain.
>
> This is similar to our github repo which is merely mirror to Apache git
> repo.
>
> The question is who has access to update readme.io for ignite and it
> must be just mirror or copy from document content hosted somewhere
> under Apache domain.
>
> On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
> <ds...@apache.org> wrote:
> > Hello Igniters,
> >
> > I think I have found a pretty cool home for our documentation:
> > http://apacheignite.readme.io/v1.0/docs
> >
> > https://readme.io is nice enough to host open source documentation for
> > free, and I like the editability and friendliness of their UI.
> >
> > I have added most of the committers as admins to the documentation wiki.
> >
> > Feel free to start contributing pages.
> >
> > D.
>
Re: New home for Ignite documentation
Posted by Henry Saputra <he...@gmail.com>.
I am not sure how readme.io works but technically the actual content
should be hosted in apache domain.
This is similar to our github repo which is merely mirror to Apache git repo.
The question is who has access to update readme.io for ignite and it
must be just mirror or copy from document content hosted somewhere
under Apache domain.
On Sun, Feb 8, 2015 at 10:25 PM, Dmitriy Setrakyan
<ds...@apache.org> wrote:
> Hello Igniters,
>
> I think I have found a pretty cool home for our documentation:
> http://apacheignite.readme.io/v1.0/docs
>
> https://readme.io is nice enough to host open source documentation for
> free, and I like the editability and friendliness of their UI.
>
> I have added most of the committers as admins to the documentation wiki.
>
> Feel free to start contributing pages.
>
> D.