ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vladimir Ozerov <voze...@gridgain.com>
Subject Re: Let's keep Apache Ignite docs up-to-date
Date Thu, 02 Nov 2017 06:27:27 GMT
+1 for moving docs under Git provided that we find a way to update docs
outside of AI release as it is possible now with readme.io.

On Thu, Nov 2, 2017 at 8:57 AM, Pavel Tupitsyn <ptupitsyn@apache.org> wrote:

> > I can edit a document and it is visible to the whole world once I click a
> save button
> I see this as a huge downside.
> Anyone can screw up entire documentation with a single misplaced click,
> and you can't even see the history or have an ability to restore the
> previous version.
>
> Right now I can go and remove any page, and you would not even know who did
> that.
> (or am I missing something? can you revert and restore things?)
>
>
> On Thu, Nov 2, 2017 at 2:35 AM, Dmitriy Setrakyan <dsetrakyan@apache.org>
> wrote:
>
> > 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