Suggestions to improve the documentation


#1

Allow Comments

The documentation is ok for now, but there are a lot of details missing. And I suggest to make it easily possible to note these missing thing via comments. Example: the Annotations page doesn’t say something about parameters, default values or nested annotations.

Forking the page wouldn’t help, because most readers would only know that they don’t know what they want to know :wink:

Version Number in URIs

The documentation should explicitly reflect the Kotlin version. I suggest an URI scheme like this:

http://kotlinlang.org/docs/0.8/reference/annotations.html
http://kotlinlang.org/docs/stable/reference/annotations.html

Whereas the latter should always point to the last stable release.

Search

A search box on the documentation pages would be helpful.

Christian


#2

I suggested (via a Git merge request) to add an "open points" section to each page, so that users can name things they'd like to know but that are missing on the page. This idea was rejected. Maybe getsatisfaction.com could be helpful instead. This is used for the Scala documentation (but seemingly ignored by the Scala documentation authors ...).


#3

How about submitting requests in YouTrack? The documentation site could then include the result of a YouTrack query to list open documentation issues?


#4

Very good suggestion. I like this even better. The JetBrains account used in this forum could then be reused for the ticket system.