V Documentation Being Presented in an Inconvenient or Awkward Way to Users

[Wajinn]

Debatably, it appears that how V's documentation is presented, is problematic. It is being presented in a way to make it easier to edit for those with existing GitHub accounts and are contributors, not all users or the general public. There is nothing wrong with that, but there is no downloadable documentation being offered, as an obvious link from the main site.

Including that documentation is now being partially presented, in sections, versus the link which shows the entire document. At the least, the link to the entire document (and maybe as a downloadable PDF) could be given in the introduction, from the io site.

1) It probably should not be assumed that everyone reaching the main .io site, is signed up for GitHub or a contributor.

The main website offers the latest version of V as a downloadable ZIP file (great). There is a good argument that such should be the case for documentation, as a PDF file. For at least the documentation and arguably for the modules too. The PDF file(s) would be based on the date of the latest release offered, when turned into a ZIP.

By the way, V offered as a ZIP and PDFs, means it can be downloadable from many different trusted or high reputation sites offering software, such as Softpedia or Major Geeks. This would naturally expand awareness about the language.

2) People can go to the site for an up to the moment version, but it should not be assumed that everyone always needs or wants that.

3) People, particularly in certain countries, can have limited Internet access.

[medvednikov]

There's also https://docs.vlang.io

Would be very easy to offer it as a zip

[Wajinn]

Something like that, but maybe the documentation would be better presented or more convenient to use in the PDF format. Would be great if V had the PDF in the same ZIP offered at the io site. Seems it would increase immediate usability.

At that point, people could also download V's ZIP from the main (or possibly chosen high reputation sites) and get started more easily. The separate PDF could also be put up at various sites as well. With corresponding date and version info, and link to main site and online version. An introduction or summary about the language can also be written, at those sites.

[JalonSolov]

If a PDF were to be created, I'd rather have it as just another artifact that can be downloaded, next to the ZIP file, rather than included in the main ZIP.

Mainly because if we start doing translated versions, I don't want ALL the various language versions to be included in the ZIP - just download the one you want separately.

Introduction/summary, there are the beginnings of that in https://github.com/vlang/edu-platform

[Wajinn]

The PDF being separate, would be fine. Understand about translations. Something else to be considered, is providing a much wider reach, with sites like wikibooks, gitbooks, or tutorialspoint.

1) In the case of wikibooks, it can be set up to provide printable versions of the documentation or downloadable PDF.

This also includes a self linking index, which works very well when saved as a PDF or downloaded as a PDF, on most browsers. Translations can be done in other languages, where there is a similar setup. And this is hosted for free.

2) In the case of gitbooks, somehow a Chinese translation already exists, before the English version.

This was done by the V contributor, lydiandy. He has pretty much set the format, in which other languages can follow.

3) Tutorialspoint is a very popular website.

In fact, I'm surprised there wasn't already a tutorial for V on there, before somebody put a course on V at Udemy.

4) edu-platform

Maybe it could be considered to eventually have a quiz after each lesson. That would be great for educational purposes, to reinforce what was taught.