Add the possibility to select the documentation version through a drop-down menu

[funder7]

Make sure to check the existing issues in this repository

Please, tell us what's the problem?

• A typo
• Wrong documentation
• Improvement of existing article
• Missing documentation
• New article needed

Please, tell us more details

Hi, wouldn't be a good idea to add a drop-down selector in the docs, to let the user switch to a newer/older version?
By doing so, an user would be able to see what's changed, and have a solid source from where to get the information, independently from his project version.

Especially now that there major changes between the upcoming release and the previous one, having such selector would give an immediate feedback to the user, communicating that the documentation has been updated.

I look to the docs frequently, and often I'm unsure about the validity of the instructions for the libraries that I'm working with. An alternative to this would be to add the creation date & update date to each article, letting the user know if something has changed.

What do you think?

[NathanaelA]

@funder7 - Thanks for the request, we are looking at doing a doc revamp (with some cool features); however I'm not sure we will want to do doc versions as that adds even more complexity to the site. In all reality we really want you using the latest because all the bug fixes are hopefully in place and it is hopefully a much stabler version. ;-)

[funder7]

@NathanaelA thank for the quick answser! I understand your point...but as a user let me tell you that more than once I'm not sure that I'm looking at the most recent information, especially now that a lot of updates are on the way.. Maybe just the creation date + last update would give an indication: if the article has been updated recently I know that I'm reading something that it's still valid, while if the article is like 2 years old, I can expect some differences!

I use official documentations a lot, for me they are like the holy grail of a library (or similar). I like NS a lot, but to be fully honest, the documentation it's the weak point!
Actually to search valid configurations for the upcoming release, I'm jumping from NS website, blog posts, Twitter... Yes, after a while you get used to it, but once you have a break for.. let's say a month, and come back to NS development, then you need to figure out again where the information are located. No chance to know if in the meanwhile something changed (no dates!).
Personally I would add a notice in the documentation, pointing towards the blog posts, if there are any crucial updates.

I don't have much time, but in case I would be happy to contribute...NS has great potential, it's a shame if it gets lost due to navigation problems!

Vue.js or lodash are good examples imho.

A scandal for newcomers!

Why don't try with a survey and see what other devs think about it?

[NathanaelA]

@funder7 - I'm not sure if you are aware nStudio has recently taken over NativeScript; so we have actually started to automate several items (including deploying the websites) from git.

We totally agree that the doc's could use some work; and as such it is something we want to do something about it -- however, at this moment I'll be honest their are several higher priority items (like getting automation fully working across all the repos). 😀

Our objective with the doc repo is to actually add the docs for all three officially supported flavors (core, angular, vue), and potentially the others un-officially supported flavors (svelte, react). So that is 5 (or more) different documentation groups; with a easy pull down to switch between the doc set. In addition the second objective with the docs is that when we accept a PR; it will auto-deploy to the doc site, no more manual maintenance. This should allow us to easily generate the change log, and have the docs in sync with the main repo much much easier.

We DO really like hearing what the community wants to see; I think that if we are automated and have automated change logs, and potentially change logs at bottom of each page then the biggest reason for separate versions pretty much vanishes.
Thoughts?

And we would welcome any help that you want to provide...

[funder7]

@NathanaelA sure I've read the blog post about nStudio... looks like there are some changes in the air :-)
Anyway I understand that in this moment there are other priorities, I imagine also that it's not easy to keep up with the documentation.

I think that you're definitively doing the right thing, by automating the release process! Actually I've just read some parts of the documentation regarding the architectural topics, that part is good and probably doesn't need any update, it's just the part that shows the latest changes for me that needs some work.
For me adding the changelog it's already a huge step ahead: having a summary from where you see all the changes can help for various reason, personally when I use a library a lot in a project, it's good to see what's changed by each update: if you are not aware of it probably you will never use the new features. Yes you can do a diff, but reading text is faster for sure :-)

Going back to NS, maybe once the documentation topic are consolidated, trying to merge similar pages can be a good idea. The information is there, it's just too fragmented: that, and the fact that you cannot place these info on a timeline, is what makes them not very useful.

Personally, I've got some problems following the recent updates, it's not easy to understand which-module-does-what, but probably that it's because I'm a bit "rusty", as nearly two months passed since the last time with NS.
The recent switch to scoped packages ( which is a great thing ), caused some headaches...that's something that does not happen in a normal situation because when you just import & run everything, now a little more tinkering is required ...once you manage to make things work it's satisfying, but when you are out of time can become a nightmare :-D

Why not add a page where all the packages are listed, with stable, current, alpha, rc versions al listed? It may seem not very useful, but consider that in my project now I've got these packages:

• nativescript (global cli)
• @nativescript/angular
• @nativescript/theme
• @nativescript/core
• @nativescript/tslint-rules
• @nativescript/webpack
• nativescript-dev-webpack
• tns-core-modules
• tns-platform-declarations
• nativescript-ui-dataform
• nativescript-unit-test-runner

These are 11 modules (plugins apart!) that must work all together, in sync....it's not easy, especially if you don't have a clue of the purpose of each package; even if you have, with 11 packages it's easy to make mistakes!
Having a published list of which versions to use with a brief description of the package, would be a super nice to have!
Like a shopping cart: a list with example configurations (angular: use a,b,c,d | code-sharing: use b,c,d,e | vue: use a,b, [email protected]). Without this recap page it's not possible, it's a treasure hunt... But jokes apart, a lot of developers don't have time/patience for this and will switch to something more direct, even if it has less features, I think.

Having updated blank projects it's important too, once you need to update: git clone, diff & life is better!

Ok... it's a bit late for me now sorry :) I hope that what I've written it's in a good enough form and doesn't sound too picky, it's just my point of view on the project.

To recap my experience with nativescript: [ 65% configuration & learning | 35% writing code ].

We DO really like hearing what the community wants to see; I think that if we are automated and have automated change logs, and potentially change logs at bottom of each page then the biggest reason for separate versions pretty much vanishes.
Thoughts?

Totally agree with this!

Surveys would help a lot to understand the community needs!

Sorry for this boring message & thanks for reading ;-) see you the next time