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 <[email protected]> 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 > <[email protected]> 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 <[email protected]> > > 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 < > [email protected]> > >> 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 < > [email protected]> > >> > 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 > >> >> <[email protected]> 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. > >> >> > >> >
