ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pavel Tupitsyn <ptupit...@apache.org>
Subject Re: Let's keep Apache Ignite docs up-to-date
Date Thu, 02 Nov 2017 05:57:31 GMT
> 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