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 <[email protected]> wrote: > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <[email protected]> > 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. >
