Organizing documentation for platforms

[Vladimir Ozerov]

Igniters,

We need to add documentation for .Net and CPP platforms. There are several
approaches:

1) Just add corresponding .Net/CPP code snippets to existing docs.
Very easy to implement, but platform users will have to constantly switch
from Java code snippets and will not understand which features exist in the
platform and which are not.

2) Place platform docs in a separate paragraph. E.g.
root
|-- Clustering
|-- ...
|-- .Net
|   |-- Clustering
|-- CPP
|   |-- Clustering

Not very good idea, we want to position .Net and CPP as a fully-fledged
products, not as some secondary extension to Java version.

3) Create separate *readme.io <http://readme.io>* space, e.g.
*https://apacheignite-dotnet.readme.io/
<https://apacheignite-dotnet.readme.io/>* and put all relevant docs here.
The most user-friendly solution, but require more work and lead to docs
duplication what will make maintenance harder.

I tend to prefer the last approach. Any ideas/thoughts?

Vladimir.

[dsetrakyan]

I agree. The last approach is the most preferable.

D.

On Mon, Sep 14, 2015 at 2:50 AM, Vladimir Ozerov <[hidden email]>
wrote:

> Igniters,
>
> We need to add documentation for .Net and CPP platforms. There are several
> approaches:
>
> 1) Just add corresponding .Net/CPP code snippets to existing docs.
> Very easy to implement, but platform users will have to constantly switch
> from Java code snippets and will not understand which features exist in the
> platform and which are not.
>
> 2) Place platform docs in a separate paragraph. E.g.
> root
> |-- Clustering
> |-- ...
> |-- .Net
> |   |-- Clustering
> |-- CPP
> |   |-- Clustering
>
> Not very good idea, we want to position .Net and CPP as a fully-fledged
> products, not as some secondary extension to Java version.
>
> 3) Create separate *readme.io <http://readme.io>* space, e.g.
> *https://apacheignite-dotnet.readme.io/
> <https://apacheignite-dotnet.readme.io/>* and put all relevant docs here.
> The most user-friendly solution, but require more work and lead to docs
> duplication what will make maintenance harder.
>
> I tend to prefer the last approach. Any ideas/thoughts?
>
> Vladimir.
>

[yzhdanov]

I like 2nd most of all.

1. Current docs have lots of general info and concepts explanation.
2. If platform doesn't support anything, you put it right on feature page.

Thanks!

Yakov
On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]> wrote:

> Igniters,
>
> We need to add documentation for .Net and CPP platforms. There are several
> approaches:
>
> 1) Just add corresponding .Net/CPP code snippets to existing docs.
> Very easy to implement, but platform users will have to constantly switch
> from Java code snippets and will not understand which features exist in the
> platform and which are not.
>
> 2) Place platform docs in a separate paragraph. E.g.
> root
> |-- Clustering
> |-- ...
> |-- .Net
> |   |-- Clustering
> |-- CPP
> |   |-- Clustering
>
> Not very good idea, we want to position .Net and CPP as a fully-fledged
> products, not as some secondary extension to Java version.
>
> 3) Create separate *readme.io <http://readme.io>* space, e.g.
> *https://apacheignite-dotnet.readme.io/
> <https://apacheignite-dotnet.readme.io/>* and put all relevant docs here.
> The most user-friendly solution, but require more work and lead to docs
> duplication what will make maintenance harder.
>
> I tend to prefer the last approach. Any ideas/thoughts?
>
> Vladimir.
>

[dsetrakyan]

We should also take into account whether Java users will be interested in
.NET/C++ and vise versa. In my opinion, the users for .NET/C++ don't
intersect with Java users, that's why I suggested a separate documentation
space for them.

On Mon, Sep 14, 2015 at 10:39 AM, Yakov Zhdanov <[hidden email]> wrote:

> I like 2nd most of all.
>
> 1. Current docs have lots of general info and concepts explanation.
> 2. If platform doesn't support anything, you put it right on feature page.
>
> Thanks!
>
> Yakov
> On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]> wrote:
>
> > Igniters,
> >
> > We need to add documentation for .Net and CPP platforms. There are
> several
> > approaches:
> >
> > 1) Just add corresponding .Net/CPP code snippets to existing docs.
> > Very easy to implement, but platform users will have to constantly switch
> > from Java code snippets and will not understand which features exist in
> the
> > platform and which are not.
> >
> > 2) Place platform docs in a separate paragraph. E.g.
> > root
> > |-- Clustering
> > |-- ...
> > |-- .Net
> > |   |-- Clustering
> > |-- CPP
> > |   |-- Clustering
> >
> > Not very good idea, we want to position .Net and CPP as a fully-fledged
> > products, not as some secondary extension to Java version.
> >
> > 3) Create separate *readme.io <http://readme.io>* space, e.g.
> > *https://apacheignite-dotnet.readme.io/
> > <https://apacheignite-dotnet.readme.io/>* and put all relevant docs
> here.
> > The most user-friendly solution, but require more work and lead to docs
> > duplication what will make maintenance harder.
> >
> > I tend to prefer the last approach. Any ideas/thoughts?
> >
> > Vladimir.
> >
>

[Vladimir Ozerov]

Igniters,

Does anyone know how what is the procedure of creating a new space in
readme.io?

On Mon, Sep 14, 2015 at 9:07 PM, Dmitriy Setrakyan <[hidden email]>
wrote:

> We should also take into account whether Java users will be interested in
> .NET/C++ and vise versa. In my opinion, the users for .NET/C++ don't
> intersect with Java users, that's why I suggested a separate documentation
> space for them.
>
> On Mon, Sep 14, 2015 at 10:39 AM, Yakov Zhdanov <[hidden email]>
> wrote:
>
> > I like 2nd most of all.
> >
> > 1. Current docs have lots of general info and concepts explanation.
> > 2. If platform doesn't support anything, you put it right on feature
> page.
> >
> > Thanks!
> >
> > Yakov
> > On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]> wrote:
> >
> > > Igniters,
> > >
> > > We need to add documentation for .Net and CPP platforms. There are
> > several
> > > approaches:
> > >
> > > 1) Just add corresponding .Net/CPP code snippets to existing docs.
> > > Very easy to implement, but platform users will have to constantly
> switch
> > > from Java code snippets and will not understand which features exist in
> > the
> > > platform and which are not.
> > >
> > > 2) Place platform docs in a separate paragraph. E.g.
> > > root
> > > |-- Clustering
> > > |-- ...
> > > |-- .Net
> > > |   |-- Clustering
> > > |-- CPP
> > > |   |-- Clustering
> > >
> > > Not very good idea, we want to position .Net and CPP as a fully-fledged
> > > products, not as some secondary extension to Java version.
> > >
> > > 3) Create separate *readme.io <http://readme.io>* space, e.g.
> > > *https://apacheignite-dotnet.readme.io/
> > > <https://apacheignite-dotnet.readme.io/>* and put all relevant docs
> > here.
> > > The most user-friendly solution, but require more work and lead to docs
> > > duplication what will make maintenance harder.
> > >
> > > I tend to prefer the last approach. Any ideas/thoughts?
> > >
> > > Vladimir.
> > >
> >
>

[Dmitriy Setrakyan]

Let me create one. I will respond here when I am done.

D.

On Tue, Sep 15, 2015 at 1:12 AM, Vladimir Ozerov <[hidden email]>
wrote:

> Igniters,
>
> Does anyone know how what is the procedure of creating a new space in
> readme.io?
>
> On Mon, Sep 14, 2015 at 9:07 PM, Dmitriy Setrakyan <[hidden email]>
> wrote:
>
> > We should also take into account whether Java users will be interested in
> > .NET/C++ and vise versa. In my opinion, the users for .NET/C++ don't
> > intersect with Java users, that's why I suggested a separate
> documentation
> > space for them.
> >
> > On Mon, Sep 14, 2015 at 10:39 AM, Yakov Zhdanov <[hidden email]>
> > wrote:
> >
> > > I like 2nd most of all.
> > >
> > > 1. Current docs have lots of general info and concepts explanation.
> > > 2. If platform doesn't support anything, you put it right on feature
> > page.
> > >
> > > Thanks!
> > >
> > > Yakov
> > > On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]> wrote:
> > >
> > > > Igniters,
> > > >
> > > > We need to add documentation for .Net and CPP platforms. There are
> > > several
> > > > approaches:
> > > >
> > > > 1) Just add corresponding .Net/CPP code snippets to existing docs.
> > > > Very easy to implement, but platform users will have to constantly
> > switch
> > > > from Java code snippets and will not understand which features exist
> in
> > > the
> > > > platform and which are not.
> > > >
> > > > 2) Place platform docs in a separate paragraph. E.g.
> > > > root
> > > > |-- Clustering
> > > > |-- ...
> > > > |-- .Net
> > > > |   |-- Clustering
> > > > |-- CPP
> > > > |   |-- Clustering
> > > >
> > > > Not very good idea, we want to position .Net and CPP as a
> fully-fledged
> > > > products, not as some secondary extension to Java version.
> > > >
> > > > 3) Create separate *readme.io <http://readme.io>* space, e.g.
> > > > *https://apacheignite-dotnet.readme.io/
> > > > <https://apacheignite-dotnet.readme.io/>* and put all relevant docs
> > > here.
> > > > The most user-friendly solution, but require more work and lead to
> docs
> > > > duplication what will make maintenance harder.
> > > >
> > > > I tend to prefer the last approach. Any ideas/thoughts?
> > > >
> > > > Vladimir.
> > > >
> > >
> >
>

[yzhdanov]

I would like everyone to think over if all docs are in a single space.
Nobody wants to split binaries and codebase. Why split documentation?

Is there ability for readmeio user to set preferred snippet language? This
way user will not have to switch on each page.

--Yakov

2015-09-15 12:31 GMT+03:00 Dmitriy Setrakyan <[hidden email]>:

> Let me create one. I will respond here when I am done.
>
> D.
>
> On Tue, Sep 15, 2015 at 1:12 AM, Vladimir Ozerov <[hidden email]>
> wrote:
>
> > Igniters,
> >
> > Does anyone know how what is the procedure of creating a new space in
> > readme.io?
> >
> > On Mon, Sep 14, 2015 at 9:07 PM, Dmitriy Setrakyan <
> [hidden email]>
> > wrote:
> >
> > > We should also take into account whether Java users will be interested
> in
> > > .NET/C++ and vise versa. In my opinion, the users for .NET/C++ don't
> > > intersect with Java users, that's why I suggested a separate
> > documentation
> > > space for them.
> > >
> > > On Mon, Sep 14, 2015 at 10:39 AM, Yakov Zhdanov <[hidden email]>
> > > wrote:
> > >
> > > > I like 2nd most of all.
> > > >
> > > > 1. Current docs have lots of general info and concepts explanation.
> > > > 2. If platform doesn't support anything, you put it right on feature
> > > page.
> > > >
> > > > Thanks!
> > > >
> > > > Yakov
> > > > On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]>
> wrote:
> > > >
> > > > > Igniters,
> > > > >
> > > > > We need to add documentation for .Net and CPP platforms. There are
> > > > several
> > > > > approaches:
> > > > >
> > > > > 1) Just add corresponding .Net/CPP code snippets to existing docs.
> > > > > Very easy to implement, but platform users will have to constantly
> > > switch
> > > > > from Java code snippets and will not understand which features
> exist
> > in
> > > > the
> > > > > platform and which are not.
> > > > >
> > > > > 2) Place platform docs in a separate paragraph. E.g.
> > > > > root
> > > > > |-- Clustering
> > > > > |-- ...
> > > > > |-- .Net
> > > > > |   |-- Clustering
> > > > > |-- CPP
> > > > > |   |-- Clustering
> > > > >
> > > > > Not very good idea, we want to position .Net and CPP as a
> > fully-fledged
> > > > > products, not as some secondary extension to Java version.
> > > > >
> > > > > 3) Create separate *readme.io <http://readme.io>* space, e.g.
> > > > > *https://apacheignite-dotnet.readme.io/
> > > > > <https://apacheignite-dotnet.readme.io/>* and put all relevant
> docs
> > > > here.
> > > > > The most user-friendly solution, but require more work and lead to
> > docs
> > > > > duplication what will make maintenance harder.
> > > > >
> > > > > I tend to prefer the last approach. Any ideas/thoughts?
> > > > >
> > > > > Vladimir.
> > > > >
> > > >
> > >
> >
>

[Vladimir Ozerov]

Yakov,

I would be happy if are able to merge all docs in a single place, but I
simply do not see how it is possible from usability perspective.
1) There are lots features which exists only in Java and make little or noe
sense in .Net/CPP. E.g., Mesos, YARN, Docker, IGFS, Hibernate, JDBC, almost
all streamers, etc.
2) This is not only matter of changing the code snippets, but inlined class
names and packages as well: E.g., Cache in Java -> *I*Cache in .Net.

On Tue, Sep 15, 2015 at 1:20 PM, Yakov Zhdanov <[hidden email]> wrote:

> I would like everyone to think over if all docs are in a single space.
> Nobody wants to split binaries and codebase. Why split documentation?
>
> Is there ability for readmeio user to set preferred snippet language? This
> way user will not have to switch on each page.
>
> --Yakov
>
> 2015-09-15 12:31 GMT+03:00 Dmitriy Setrakyan <[hidden email]>:
>
> > Let me create one. I will respond here when I am done.
> >
> > D.
> >
> > On Tue, Sep 15, 2015 at 1:12 AM, Vladimir Ozerov <[hidden email]>
> > wrote:
> >
> > > Igniters,
> > >
> > > Does anyone know how what is the procedure of creating a new space in
> > > readme.io?
> > >
> > > On Mon, Sep 14, 2015 at 9:07 PM, Dmitriy Setrakyan <
> > [hidden email]>
> > > wrote:
> > >
> > > > We should also take into account whether Java users will be
> interested
> > in
> > > > .NET/C++ and vise versa. In my opinion, the users for .NET/C++ don't
> > > > intersect with Java users, that's why I suggested a separate
> > > documentation
> > > > space for them.
> > > >
> > > > On Mon, Sep 14, 2015 at 10:39 AM, Yakov Zhdanov <[hidden email]
> >
> > > > wrote:
> > > >
> > > > > I like 2nd most of all.
> > > > >
> > > > > 1. Current docs have lots of general info and concepts explanation.
> > > > > 2. If platform doesn't support anything, you put it right on
> feature
> > > > page.
> > > > >
> > > > > Thanks!
> > > > >
> > > > > Yakov
> > > > > On Sep 14, 2015 12:51, "Vladimir Ozerov" <[hidden email]>
> > wrote:
> > > > >
> > > > > > Igniters,
> > > > > >
> > > > > > We need to add documentation for .Net and CPP platforms. There
> are
> > > > > several
> > > > > > approaches:
> > > > > >
> > > > > > 1) Just add corresponding .Net/CPP code snippets to existing
> docs.
> > > > > > Very easy to implement, but platform users will have to
> constantly
> > > > switch
> > > > > > from Java code snippets and will not understand which features
> > exist
> > > in
> > > > > the
> > > > > > platform and which are not.
> > > > > >
> > > > > > 2) Place platform docs in a separate paragraph. E.g.
> > > > > > root
> > > > > > |-- Clustering
> > > > > > |-- ...
> > > > > > |-- .Net
> > > > > > |   |-- Clustering
> > > > > > |-- CPP
> > > > > > |   |-- Clustering
> > > > > >
> > > > > > Not very good idea, we want to position .Net and CPP as a
> > > fully-fledged
> > > > > > products, not as some secondary extension to Java version.
> > > > > >
> > > > > > 3) Create separate *readme.io <http://readme.io>* space, e.g.
> > > > > > *https://apacheignite-dotnet.readme.io/
> > > > > > <https://apacheignite-dotnet.readme.io/>* and put all relevant
> > docs
> > > > > here.
> > > > > > The most user-friendly solution, but require more work and lead
> to
> > > docs
> > > > > > duplication what will make maintenance harder.
> > > > > >
> > > > > > I tend to prefer the last approach. Any ideas/thoughts?
> > > > > >
> > > > > > Vladimir.
> > > > > >
> > > > >
> > > >
> > >
> >
>