I am going to repeat my previous comment, since it somehow got lost in the discussion:
The main value of readme is that I can edit a document and it is visible to the whole world once I click a save button, without any git commands or builds. If anyone in the community can suggest a tool that will work the same way with Apache git repository directly, please send it here. D. On Wed, Nov 1, 2017 at 4:26 AM, Anton Vinogradov <avinogra...@gridgain.com> wrote: > +1 to Pavel's proposal, > > > Markdown can also be visualized by many IDEs, so it is easy to edit > locally. > IDEA shows Markdown out of the box. > > Yakov, > > > having docs under separate git repository > We should not use separate git repo, Apache Ignite repo should be used. > Documentation should be a part of pull request. > > On Wed, Nov 1, 2017 at 10:08 AM, Pavel Tupitsyn <ptupit...@apache.org> > wrote: > > > Denis, > > > > > Could you show me any example of such a documentation where docs are > > stored in git and can be visualized by GitHub (dev stage) and 3rd party > > engine (release on the site)? > > > > 1) Apache Spark > > Source: https://github.com/apache/spark/tree/master/docs > > Docs: https://spark.apache.org/documentation.html > > (uses Jekyll) > > > > 2) Microsoft .NET > > Source: https://github.com/dotnet/docs > > Docs: https://docs.microsoft.com/en-us/dotnet/ > > (uses DocFX) > > > > > > Both of these engines (Jekyll and DocFX) use markdown, which can be > > visualized by github, and converted to HTML for the web site. > > Markdown can also be visualized by many IDEs, so it is easy to edit > > locally. > > > > Ideally, API docs (javadoc) should be integrated with the rest of the > docs, > > so users can navigate to the corresponding APIs. > > This can't be achieved nicely with readme.io. > > > > > > > having docs under separate git repository > > I don't think we need a separate repo, we can just create branches in our > > main repo for that. > > It is nice to have everything in one place. > > > > On Wed, Nov 1, 2017 at 6:30 AM, Dmitriy Setrakyan <dsetrak...@apache.org > > > > wrote: > > > > > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yzhda...@apache.org> > > > wrote: > > > > > > > I would also consider having docs under separate git repository. > > Separate > > > > since we need to have an opportunity to revisit documentation for > > already > > > > released versions. > > > > > > > > > > This should not be a problem. > > > > > >
