User Feedback + Make /type/<foo> and /routine/<foo> docs be a reference only

[zoffixznet]

There was some feedback on the language and later more specific issues pointed out with the docs.

Some of the navigational issues will be resolved by the site's redesign to a dynamic version (to be done some time in first quarter of 2018). NOTE: It wasn't.

I too think that /type/* and /routine/* docs should be just reference material. They should describe all the details about routine's/Type's behaviour but should assume the reader already has some familiarity with the language and is just looking for edge-case details, list of all accepted arguments and return values, or a refresher material.

The /language/* docs on the other hand, should be more of beginner-aimed, tutorial-style docs where the language bits are explained in more general terms, along with examples and explanation of how all the pieces fit together. These docs would simply link to /type/*//routine/* as a "see for details" type of links, so that we don't repeat all the edge cases and all possible accepted arguments in /language/* docs.

---

(some of the more prominent bits quoted from OP:)

One thing I hit a lot is that the information I actually needed was spread over several documents, and it wasn't obvious at first which one I should hit.

I'd expect the Type documentation to be more man page-like, laying out a simple reference of each individual piece of functionality, which is what you get later in the Signatures doc in the "Methods" section. Basically, the entire "Signature Literal" sections should be removed from there and dropped into Functions.

As a more specific case, there doesn't seem to be a documented way to have a function's return type be an Array with the types inside further constrained (array of ints, for example). After some experimenting, I found that it's --> Array[Int], which might be what you expect if you used Moose on Perl5. It's not explicitly laid out anywhere I could find, though.

[tisonkun]

Our /routine/* is not independent, they collect the doc from /language/* and /type/*. This should be resolved if we want to separate beginner parts from detailed parts.

I think to set a example how to rearrange the doc, we can start with Grammar, Grammar Tutorial and types relevant. Because to fix this issue, there should not be both Grammar and Grammar Tutorial in /language obviously, and Grammars are quite complete subset of the whole language, that is, we can refresh them while avoiding involve too many other parts

[tisonkun]

And after the discuss has achieved result, we should modify CONTRIBUTING.md and STYLEGUIDE.md to build a standard of what the doc need to be.

[JJ]

Those documents have changed a lot since this issue was written. /Language documents look more like tutorials, and the rest are more for reference. Can you please check that this has been addressed, and if it has not, propose some change?

[Altai-man]

Right now, we have just the structure described in OP, Language pages are tutorial-like and types/subs are man-like. Re-open if disagree.