Link guide about type syntax more prominently

[CrossEye]

(porting from ramda/ramda#1960 -- wonder if there's an automated way to do this?)

---

Carrying over from StackOverflow's "Where can I find an explanation/summary of symbols used to explain functional programming, specifically Ramda.js?".

The wiki article is good, but it should be linked more visibly. Somewhere on the docs page for sure, maybe somewhere else as well. Ideas?

[buzzdecafe]

wonder if there's an automated way to do this?

yes, but not via github directly. I moved some threads over before, but used an external tool that hits github API

[MattMS]

Just to confirm, the Stack Overflow answer is just a copy (possibly older than) the current wiki article?

It should be easy to make up another page and link it from the menu.
The hardest part now (as always) is naming the link: Type signatures or something else?

[CrossEye]

The SO answer was up-to-date as of yesterday. If anyone has edited the wiki since, it's fallen out-of-date.

I think the point is that we have a number of additional bits of documentation we would like to include; we need to figure out how to include them all. I have been lax in following this repo, even though I'm impressed with the work being done recently. I have to catch up to see if anything related has already been done.

But my thought is that we don't really need the ReadMe as our main page. We should have a bespoke documentation page, and it could then incorporate small pieces and link to larger ones like this. But I haven't thought at all about how to accomplish that, nor really seen what else has been done here lately.

[jigargosar]

Couple of suggestions, (well... one too many)

• I bet if "open chat" was embedded in the "documentation page" most people will easily find solutions to their problems. We could then update the wiki.
• Rename "Documentation" to "API"
• Add link to wiki on top bar, and name it "Docs"
• Rename "Try Ramda" to "Try Now!"
• home page should look something similar to https://www.haskell.org/
  ** where we succinctly explain the motivation behind Ramda, and purpose it serves.
• Website Look and feel is Important, I know we are not trying to sell. But we want to promote "Functional Programming" to be a mainstream alternative.
• I am willing to create pull requests, for any of the above. This work is more in my alley then "writing content" ;)

[CrossEye]

• I bet if "open chat" was embedded in the "documentation page" most people will easily find solutions to their problems. We could then update the wiki.

See #100 and #138

• Rename "Documentation" to "API"

Yes

• Add link to wiki on top bar, and name it "Docs"

I would rather have a curated list of documents, some perhaps pulled from the wiki, but organized as we like, rather than just a drop-them-on-the-wiki link.

• Rename "Try Ramda" to "Try Now!"

meh

• home page should look something similar to https://www.haskell.org/
  ** where we succinctly explain the motivation behind Ramda, and purpose it serves.

I don't find that page particularly compelling. Can you explain why you do?

• Website Look and feel is Important, I know we are not trying to sell. But we want to promote "Functional Programming" to be a mainstream alternative.

I still prefer to focus mostly on how and what and not why, leaving most all sales pitches to a minimum. I believe there is still a fair bit of work to do to get our docs as useful as they could be, but that's what I'd like to focus on: usefulness. I think look and feel can be very helpful in that, and I would certainly rather they be pleasing to the eye rather than painful, but I think the most important points are the organization of the material, followed by the ease of maintenance of that material.

[CrossEye]

• I am willing to create pull requests, for any of the above. This work is more in my alley then "writing content" ;)

We'd absolutely love the help!

[jigargosar]

@CrossEye I understand your point of view.

• I am not recommending these changes to be permanent.
• Most of these are low hanging fruits, which will help immediately.

I would rather have a curated list of documents, some perhaps pulled from the wiki, but organized as we like, rather than just a drop-them-on-the-wiki link.

• Agreed, but before we get there, let's get the wiki link up and running
• Regarding chat, "Proposal: Add link to gitter room in top nav #100 and Add Gitter Sidecar to home page #138" I was specifically referring it to be available on API page. Because that's the most important page right now.

I don't find that page particularly compelling. Can you explain why you do?

• The Best part about that page is "Tryit/Got 5 minutes?" section. Embedded repl, with mini tutorial.
• Second thing I like is the "Declarative, statically typed code" section, which has a code snipped. Right there in the Jumbotron.
• Third: features section, with explanation and code samples that expand inline on click.
• And of course typography, and negative space.
• When I said "look and feel", I only mean typography, and negative space. Not sales pitch.
• I would like to make these changes to home page, keeping in mind our focus on "how & what".

On a side note, when working on manual, I realized that being able to run code examples while we are reading it, is very important.
I was thinking of creating an interactive version of the manual.

This brings me back the API page, where tryin repl opens in a new window, it would be much better if it expanded inline. And there be a "?" symbol, after every type signature. pointing to corresponding wiki page.

As you can see I am really passionate about Ramda, specifically learning and spreading awareness of "Functional Programming in JS"

When I said "promote Functional Programming" I meant marketing, not sales. I am will to invest my time in marketing. Everyone doesn't have to do that. I want to kill the ignorance, misconceptions related to FP. And by marketing I mean, spreading accurate awareness, so that everyone can make informed decision. Ramda's home page is one place where that can be done. (Although that's not the only option)

[MattMS]

@jigargosar @CrossEye would it be better to continue this discussion in #142?

I'll quickly add that I'm a fan of the idea of embedding the REPL in more places (home page, docs), and I believe that is one of the main goals of the REPL repo.