ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dmitriy Setrakyan <dsetrak...@apache.org>
Subject Re: Let's keep Apache Ignite docs up-to-date
Date Wed, 01 Nov 2017 23:35:17 GMT
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 <avinogradov@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 <ptupitsyn@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 <dsetrakyan@apache.org
> >
> > wrote:
> >
> > > On Tue, Oct 31, 2017 at 8:15 PM, Yakov Zhdanov <yzhdanov@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.
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message