You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Andrey Kurdumov <ka...@googlemail.com> on 2015/08/05 14:57:25 UTC
[DISCUSS] Docs improvements
Hi all,
I want to made small improvements to the current version of Docs meanwhile
Dmitry Blotsky working on Jekill. Want do discuss proposed changes before
implementing them.
My ultimate goal is to be able publish each version of docs/language
independently. I want faster releases for fixes in translation and docs,
and be able fix older docs too.
Please correct me if this is not possible with existing infrastructure.
Here list of things:
1. Separate version dropdown on two parts. Language and version. Right now
if you try select non English version you have to scroll over English
versions a lot.
2. Provide warning about not latest documentation (Using JS) Will put
current version in the docs and check some JSON fiels which will list all
versions per language.
3. Provide No Javascript version of langauge selector checkboxes.
4. Create new source file for language TOC.md which will be used for
generating left sidebar in the existing docs design. So far, that TOC would
duplicate Overview page as it is now, but want to improve it further later
on. That's breaking change which affects older docs, so I will create such
TOC files for these old docs too, and verify that existing output would be
exactly the same as it is now.
To implement that I want to create new shared area on the website
`docs/common` folder and `docs/<lang>/common` folder. That folders will
contains
a) `docs/common/langdata.json` - JSON with list of languages + latest
version per language
b) `docs/ru/versionselector.html` - HTML file where use could change
language or version when JS is disabled in browser.
I extremely want create 1 and 2 before next release. That's rather small
changes, but need community agreement on implementing that.
Re: [DISCUSS] Docs improvements
Posted by Dmitry Blotsky <db...@microsoft.com>.
Hey folks,
Sorry, I only just caught up with this discussion today. There is now a prototype of the docs/website rework, which addresses points 1-4, and it’s temporarily deployed here: http://cordova.io/use-the-force-luke (the link is arbitrary so that it’s not accidentally crawlable).
Kindly,
Dmitry
On Aug 5, 2015, at 5:57 AM, Andrey Kurdumov <ka...@googlemail.com>> wrote:
Hi all,
I want to made small improvements to the current version of Docs meanwhile
Dmitry Blotsky working on Jekill. Want do discuss proposed changes before
implementing them.
My ultimate goal is to be able publish each version of docs/language
independently. I want faster releases for fixes in translation and docs,
and be able fix older docs too.
Please correct me if this is not possible with existing infrastructure.
Here list of things:
1. Separate version dropdown on two parts. Language and version. Right now
if you try select non English version you have to scroll over English
versions a lot.
2. Provide warning about not latest documentation (Using JS) Will put
current version in the docs and check some JSON fiels which will list all
versions per language.
3. Provide No Javascript version of langauge selector checkboxes.
4. Create new source file for language TOC.md which will be used for
generating left sidebar in the existing docs design. So far, that TOC would
duplicate Overview page as it is now, but want to improve it further later
on. That's breaking change which affects older docs, so I will create such
TOC files for these old docs too, and verify that existing output would be
exactly the same as it is now.
To implement that I want to create new shared area on the website
`docs/common` folder and `docs/<lang>/common` folder. That folders will
contains
a) `docs/common/langdata.json` - JSON with list of languages + latest
version per language
b) `docs/ru/versionselector.html` - HTML file where use could change
language or version when JS is disabled in browser.
I extremely want create 1 and 2 before next release. That's rather small
changes, but need community agreement on implementing that.
Re: [DISCUSS] Docs improvements
Posted by Andrey Kurdumov <ka...@googlemail.com>.
That's partially related to proposal. All these changes could be found in
ancient JIRA issues.
We talk with Dmitry about moving to Jekyll. I'm not 100% sure how it will
works for translation, so we decide to move together on same direction
simultaneously. I periodically check their progress and trying to give
feedback.
They have active development and for me due to time difference hard to
effectively together with them.
But I think that while they are working,our users should have better
experience with docs.
Re: [DISCUSS] Docs improvements
Posted by Jesse <pu...@gmail.com>.
Looks great Andrey!
My team is hiring!
@purplecabbage
risingj.com
On Thu, Aug 6, 2015 at 10:16 AM, Victor Sosa <so...@gmail.com> wrote:
> It's great to have documentation with the lang and version in separated
> controls.
> Question, how this relates to this proposal?
>
> https://cordova.slack.com/files/cpsloal/F08HJRR1C/Update_Docs_UI_for_cordova_io
>
> I can see it has the same controls, but wondering if the approaches are the
> same (and hope shared code) or same UI layout but different approach
>
> On Thu, Aug 6, 2015 at 11:46 AM Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > Here first try:
> >
> > http://cordovadocs.azurewebsites.net/en/edge/index.html
> > http://cordovadocs.azurewebsites.net/es/edge/index.html
> > http://cordovadocs.azurewebsites.net/ru/edge/index.html
> >
> > Now it is has splitted lang and version + display message when you see
> not
> > latest version. Latest version is not only edge, but also latest separate
> > version, so message appear only if see 5.0.0 in English and 3.4.0 in
> > Spanish.
> >
> >
> > 2015-08-06 4:24 GMT+06:00 Victor Sosa <so...@gmail.com>:
> >
> > > Yes, please go ahead! :D
> > >
> > > On Wed, Aug 5, 2015 at 4:25 PM Carlos Santana <cs...@gmail.com>
> > > wrote:
> > >
> > > > +1 Andrey
> > > >
> > > > On Wed, Aug 5, 2015 at 2:27 PM Steven Gill <st...@gmail.com>
> > > wrote:
> > > >
> > > > > Do it!
> > > > >
> > > > > On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
> > > > >
> > > > > > Sgtm!
> > > > > > On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <
> > > > kant2002@googlemail.com>
> > > > > > wrote:
> > > > > >
> > > > > > > Hi all,
> > > > > > >
> > > > > > > I want to made small improvements to the current version of
> Docs
> > > > > > meanwhile
> > > > > > > Dmitry Blotsky working on Jekill. Want do discuss proposed
> > changes
> > > > > before
> > > > > > > implementing them.
> > > > > > >
> > > > > > > My ultimate goal is to be able publish each version of
> > > docs/language
> > > > > > > independently. I want faster releases for fixes in translation
> > and
> > > > > docs,
> > > > > > > and be able fix older docs too.
> > > > > > > Please correct me if this is not possible with existing
> > > > infrastructure.
> > > > > > >
> > > > > > > Here list of things:
> > > > > > > 1. Separate version dropdown on two parts. Language and
> version.
> > > > Right
> > > > > > now
> > > > > > > if you try select non English version you have to scroll over
> > > English
> > > > > > > versions a lot.
> > > > > > > 2. Provide warning about not latest documentation (Using JS)
> Will
> > > put
> > > > > > > current version in the docs and check some JSON fiels which
> will
> > > list
> > > > > all
> > > > > > > versions per language.
> > > > > > > 3. Provide No Javascript version of langauge selector
> checkboxes.
> > > > > > > 4. Create new source file for language TOC.md which will be
> used
> > > for
> > > > > > > generating left sidebar in the existing docs design. So far,
> that
> > > TOC
> > > > > > would
> > > > > > > duplicate Overview page as it is now, but want to improve it
> > > further
> > > > > > later
> > > > > > > on. That's breaking change which affects older docs, so I will
> > > create
> > > > > > such
> > > > > > > TOC files for these old docs too, and verify that existing
> output
> > > > would
> > > > > > be
> > > > > > > exactly the same as it is now.
> > > > > > >
> > > > > > > To implement that I want to create new shared area on the
> website
> > > > > > > `docs/common` folder and `docs/<lang>/common` folder. That
> > folders
> > > > will
> > > > > > > contains
> > > > > > > a) `docs/common/langdata.json` - JSON with list of languages +
> > > latest
> > > > > > > version per language
> > > > > > > b) `docs/ru/versionselector.html` - HTML file where use could
> > > change
> > > > > > > language or version when JS is disabled in browser.
> > > > > > >
> > > > > > > I extremely want create 1 and 2 before next release. That's
> > rather
> > > > > small
> > > > > > > changes, but need community agreement on implementing that.
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Docs improvements
Posted by Victor Sosa <so...@gmail.com>.
It's great to have documentation with the lang and version in separated
controls.
Question, how this relates to this proposal?
https://cordova.slack.com/files/cpsloal/F08HJRR1C/Update_Docs_UI_for_cordova_io
I can see it has the same controls, but wondering if the approaches are the
same (and hope shared code) or same UI layout but different approach
On Thu, Aug 6, 2015 at 11:46 AM Andrey Kurdumov <ka...@googlemail.com>
wrote:
> Here first try:
>
> http://cordovadocs.azurewebsites.net/en/edge/index.html
> http://cordovadocs.azurewebsites.net/es/edge/index.html
> http://cordovadocs.azurewebsites.net/ru/edge/index.html
>
> Now it is has splitted lang and version + display message when you see not
> latest version. Latest version is not only edge, but also latest separate
> version, so message appear only if see 5.0.0 in English and 3.4.0 in
> Spanish.
>
>
> 2015-08-06 4:24 GMT+06:00 Victor Sosa <so...@gmail.com>:
>
> > Yes, please go ahead! :D
> >
> > On Wed, Aug 5, 2015 at 4:25 PM Carlos Santana <cs...@gmail.com>
> > wrote:
> >
> > > +1 Andrey
> > >
> > > On Wed, Aug 5, 2015 at 2:27 PM Steven Gill <st...@gmail.com>
> > wrote:
> > >
> > > > Do it!
> > > >
> > > > On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
> > > >
> > > > > Sgtm!
> > > > > On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <
> > > kant2002@googlemail.com>
> > > > > wrote:
> > > > >
> > > > > > Hi all,
> > > > > >
> > > > > > I want to made small improvements to the current version of Docs
> > > > > meanwhile
> > > > > > Dmitry Blotsky working on Jekill. Want do discuss proposed
> changes
> > > > before
> > > > > > implementing them.
> > > > > >
> > > > > > My ultimate goal is to be able publish each version of
> > docs/language
> > > > > > independently. I want faster releases for fixes in translation
> and
> > > > docs,
> > > > > > and be able fix older docs too.
> > > > > > Please correct me if this is not possible with existing
> > > infrastructure.
> > > > > >
> > > > > > Here list of things:
> > > > > > 1. Separate version dropdown on two parts. Language and version.
> > > Right
> > > > > now
> > > > > > if you try select non English version you have to scroll over
> > English
> > > > > > versions a lot.
> > > > > > 2. Provide warning about not latest documentation (Using JS) Will
> > put
> > > > > > current version in the docs and check some JSON fiels which will
> > list
> > > > all
> > > > > > versions per language.
> > > > > > 3. Provide No Javascript version of langauge selector checkboxes.
> > > > > > 4. Create new source file for language TOC.md which will be used
> > for
> > > > > > generating left sidebar in the existing docs design. So far, that
> > TOC
> > > > > would
> > > > > > duplicate Overview page as it is now, but want to improve it
> > further
> > > > > later
> > > > > > on. That's breaking change which affects older docs, so I will
> > create
> > > > > such
> > > > > > TOC files for these old docs too, and verify that existing output
> > > would
> > > > > be
> > > > > > exactly the same as it is now.
> > > > > >
> > > > > > To implement that I want to create new shared area on the website
> > > > > > `docs/common` folder and `docs/<lang>/common` folder. That
> folders
> > > will
> > > > > > contains
> > > > > > a) `docs/common/langdata.json` - JSON with list of languages +
> > latest
> > > > > > version per language
> > > > > > b) `docs/ru/versionselector.html` - HTML file where use could
> > change
> > > > > > language or version when JS is disabled in browser.
> > > > > >
> > > > > > I extremely want create 1 and 2 before next release. That's
> rather
> > > > small
> > > > > > changes, but need community agreement on implementing that.
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Docs improvements
Posted by Andrey Kurdumov <ka...@googlemail.com>.
Here first try:
http://cordovadocs.azurewebsites.net/en/edge/index.html
http://cordovadocs.azurewebsites.net/es/edge/index.html
http://cordovadocs.azurewebsites.net/ru/edge/index.html
Now it is has splitted lang and version + display message when you see not
latest version. Latest version is not only edge, but also latest separate
version, so message appear only if see 5.0.0 in English and 3.4.0 in
Spanish.
2015-08-06 4:24 GMT+06:00 Victor Sosa <so...@gmail.com>:
> Yes, please go ahead! :D
>
> On Wed, Aug 5, 2015 at 4:25 PM Carlos Santana <cs...@gmail.com>
> wrote:
>
> > +1 Andrey
> >
> > On Wed, Aug 5, 2015 at 2:27 PM Steven Gill <st...@gmail.com>
> wrote:
> >
> > > Do it!
> > >
> > > On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
> > >
> > > > Sgtm!
> > > > On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <
> > kant2002@googlemail.com>
> > > > wrote:
> > > >
> > > > > Hi all,
> > > > >
> > > > > I want to made small improvements to the current version of Docs
> > > > meanwhile
> > > > > Dmitry Blotsky working on Jekill. Want do discuss proposed changes
> > > before
> > > > > implementing them.
> > > > >
> > > > > My ultimate goal is to be able publish each version of
> docs/language
> > > > > independently. I want faster releases for fixes in translation and
> > > docs,
> > > > > and be able fix older docs too.
> > > > > Please correct me if this is not possible with existing
> > infrastructure.
> > > > >
> > > > > Here list of things:
> > > > > 1. Separate version dropdown on two parts. Language and version.
> > Right
> > > > now
> > > > > if you try select non English version you have to scroll over
> English
> > > > > versions a lot.
> > > > > 2. Provide warning about not latest documentation (Using JS) Will
> put
> > > > > current version in the docs and check some JSON fiels which will
> list
> > > all
> > > > > versions per language.
> > > > > 3. Provide No Javascript version of langauge selector checkboxes.
> > > > > 4. Create new source file for language TOC.md which will be used
> for
> > > > > generating left sidebar in the existing docs design. So far, that
> TOC
> > > > would
> > > > > duplicate Overview page as it is now, but want to improve it
> further
> > > > later
> > > > > on. That's breaking change which affects older docs, so I will
> create
> > > > such
> > > > > TOC files for these old docs too, and verify that existing output
> > would
> > > > be
> > > > > exactly the same as it is now.
> > > > >
> > > > > To implement that I want to create new shared area on the website
> > > > > `docs/common` folder and `docs/<lang>/common` folder. That folders
> > will
> > > > > contains
> > > > > a) `docs/common/langdata.json` - JSON with list of languages +
> latest
> > > > > version per language
> > > > > b) `docs/ru/versionselector.html` - HTML file where use could
> change
> > > > > language or version when JS is disabled in browser.
> > > > >
> > > > > I extremely want create 1 and 2 before next release. That's rather
> > > small
> > > > > changes, but need community agreement on implementing that.
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Docs improvements
Posted by Victor Sosa <so...@gmail.com>.
Yes, please go ahead! :D
On Wed, Aug 5, 2015 at 4:25 PM Carlos Santana <cs...@gmail.com> wrote:
> +1 Andrey
>
> On Wed, Aug 5, 2015 at 2:27 PM Steven Gill <st...@gmail.com> wrote:
>
> > Do it!
> >
> > On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
> >
> > > Sgtm!
> > > On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <
> kant2002@googlemail.com>
> > > wrote:
> > >
> > > > Hi all,
> > > >
> > > > I want to made small improvements to the current version of Docs
> > > meanwhile
> > > > Dmitry Blotsky working on Jekill. Want do discuss proposed changes
> > before
> > > > implementing them.
> > > >
> > > > My ultimate goal is to be able publish each version of docs/language
> > > > independently. I want faster releases for fixes in translation and
> > docs,
> > > > and be able fix older docs too.
> > > > Please correct me if this is not possible with existing
> infrastructure.
> > > >
> > > > Here list of things:
> > > > 1. Separate version dropdown on two parts. Language and version.
> Right
> > > now
> > > > if you try select non English version you have to scroll over English
> > > > versions a lot.
> > > > 2. Provide warning about not latest documentation (Using JS) Will put
> > > > current version in the docs and check some JSON fiels which will list
> > all
> > > > versions per language.
> > > > 3. Provide No Javascript version of langauge selector checkboxes.
> > > > 4. Create new source file for language TOC.md which will be used for
> > > > generating left sidebar in the existing docs design. So far, that TOC
> > > would
> > > > duplicate Overview page as it is now, but want to improve it further
> > > later
> > > > on. That's breaking change which affects older docs, so I will create
> > > such
> > > > TOC files for these old docs too, and verify that existing output
> would
> > > be
> > > > exactly the same as it is now.
> > > >
> > > > To implement that I want to create new shared area on the website
> > > > `docs/common` folder and `docs/<lang>/common` folder. That folders
> will
> > > > contains
> > > > a) `docs/common/langdata.json` - JSON with list of languages + latest
> > > > version per language
> > > > b) `docs/ru/versionselector.html` - HTML file where use could change
> > > > language or version when JS is disabled in browser.
> > > >
> > > > I extremely want create 1 and 2 before next release. That's rather
> > small
> > > > changes, but need community agreement on implementing that.
> > > >
> > >
> >
>
Re: [DISCUSS] Docs improvements
Posted by Carlos Santana <cs...@gmail.com>.
+1 Andrey
On Wed, Aug 5, 2015 at 2:27 PM Steven Gill <st...@gmail.com> wrote:
> Do it!
>
> On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
>
> > Sgtm!
> > On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <ka...@googlemail.com>
> > wrote:
> >
> > > Hi all,
> > >
> > > I want to made small improvements to the current version of Docs
> > meanwhile
> > > Dmitry Blotsky working on Jekill. Want do discuss proposed changes
> before
> > > implementing them.
> > >
> > > My ultimate goal is to be able publish each version of docs/language
> > > independently. I want faster releases for fixes in translation and
> docs,
> > > and be able fix older docs too.
> > > Please correct me if this is not possible with existing infrastructure.
> > >
> > > Here list of things:
> > > 1. Separate version dropdown on two parts. Language and version. Right
> > now
> > > if you try select non English version you have to scroll over English
> > > versions a lot.
> > > 2. Provide warning about not latest documentation (Using JS) Will put
> > > current version in the docs and check some JSON fiels which will list
> all
> > > versions per language.
> > > 3. Provide No Javascript version of langauge selector checkboxes.
> > > 4. Create new source file for language TOC.md which will be used for
> > > generating left sidebar in the existing docs design. So far, that TOC
> > would
> > > duplicate Overview page as it is now, but want to improve it further
> > later
> > > on. That's breaking change which affects older docs, so I will create
> > such
> > > TOC files for these old docs too, and verify that existing output would
> > be
> > > exactly the same as it is now.
> > >
> > > To implement that I want to create new shared area on the website
> > > `docs/common` folder and `docs/<lang>/common` folder. That folders will
> > > contains
> > > a) `docs/common/langdata.json` - JSON with list of languages + latest
> > > version per language
> > > b) `docs/ru/versionselector.html` - HTML file where use could change
> > > language or version when JS is disabled in browser.
> > >
> > > I extremely want create 1 and 2 before next release. That's rather
> small
> > > changes, but need community agreement on implementing that.
> > >
> >
>
Re: [DISCUSS] Docs improvements
Posted by Steven Gill <st...@gmail.com>.
Do it!
On Wed, Aug 5, 2015 at 8:55 AM, Brian LeRoux <b...@brian.io> wrote:
> Sgtm!
> On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <ka...@googlemail.com>
> wrote:
>
> > Hi all,
> >
> > I want to made small improvements to the current version of Docs
> meanwhile
> > Dmitry Blotsky working on Jekill. Want do discuss proposed changes before
> > implementing them.
> >
> > My ultimate goal is to be able publish each version of docs/language
> > independently. I want faster releases for fixes in translation and docs,
> > and be able fix older docs too.
> > Please correct me if this is not possible with existing infrastructure.
> >
> > Here list of things:
> > 1. Separate version dropdown on two parts. Language and version. Right
> now
> > if you try select non English version you have to scroll over English
> > versions a lot.
> > 2. Provide warning about not latest documentation (Using JS) Will put
> > current version in the docs and check some JSON fiels which will list all
> > versions per language.
> > 3. Provide No Javascript version of langauge selector checkboxes.
> > 4. Create new source file for language TOC.md which will be used for
> > generating left sidebar in the existing docs design. So far, that TOC
> would
> > duplicate Overview page as it is now, but want to improve it further
> later
> > on. That's breaking change which affects older docs, so I will create
> such
> > TOC files for these old docs too, and verify that existing output would
> be
> > exactly the same as it is now.
> >
> > To implement that I want to create new shared area on the website
> > `docs/common` folder and `docs/<lang>/common` folder. That folders will
> > contains
> > a) `docs/common/langdata.json` - JSON with list of languages + latest
> > version per language
> > b) `docs/ru/versionselector.html` - HTML file where use could change
> > language or version when JS is disabled in browser.
> >
> > I extremely want create 1 and 2 before next release. That's rather small
> > changes, but need community agreement on implementing that.
> >
>
Re: [DISCUSS] Docs improvements
Posted by Brian LeRoux <b...@brian.io>.
Sgtm!
On Wed, Aug 5, 2015 at 6:05 AM Andrey Kurdumov <ka...@googlemail.com>
wrote:
> Hi all,
>
> I want to made small improvements to the current version of Docs meanwhile
> Dmitry Blotsky working on Jekill. Want do discuss proposed changes before
> implementing them.
>
> My ultimate goal is to be able publish each version of docs/language
> independently. I want faster releases for fixes in translation and docs,
> and be able fix older docs too.
> Please correct me if this is not possible with existing infrastructure.
>
> Here list of things:
> 1. Separate version dropdown on two parts. Language and version. Right now
> if you try select non English version you have to scroll over English
> versions a lot.
> 2. Provide warning about not latest documentation (Using JS) Will put
> current version in the docs and check some JSON fiels which will list all
> versions per language.
> 3. Provide No Javascript version of langauge selector checkboxes.
> 4. Create new source file for language TOC.md which will be used for
> generating left sidebar in the existing docs design. So far, that TOC would
> duplicate Overview page as it is now, but want to improve it further later
> on. That's breaking change which affects older docs, so I will create such
> TOC files for these old docs too, and verify that existing output would be
> exactly the same as it is now.
>
> To implement that I want to create new shared area on the website
> `docs/common` folder and `docs/<lang>/common` folder. That folders will
> contains
> a) `docs/common/langdata.json` - JSON with list of languages + latest
> version per language
> b) `docs/ru/versionselector.html` - HTML file where use could change
> language or version when JS is disabled in browser.
>
> I extremely want create 1 and 2 before next release. That's rather small
> changes, but need community agreement on implementing that.
>