Documentation - Replace "Set, Map and equality" from readme with a link to the Wiki and use "Prelude−ts user guide" as Wiki home

[lppedd]

As per title, I think the "Set, Map and equality" paragraph in the readme is redundant. The same thing can be found in the Wiki.

Also, in the Wiki it's a bit uncomfortable having to click on the "Prelude−ts user guide" link to read something. Wouldn't it be better to make it the Wiki home?

Edit: for the Predicate Wiki paragraph, maybe you can add this real-world example: Before:

let filtered = jobs.filter(job => filteredDomains.includes(job.domain))

if (selectedTagsIds.length) {
  filtered = filtered.filter(job => job.tags.some(tag => selectedTagsIds.includes(tag)))
}

const jobNameFilter = filteredJobName.trim()

if (jobNameFilter) {
  filtered =
      filtered.filter(job =>
          job.name.toLowerCase().includes(jobNameFilter.toLowerCase()))
}

return filtered

After:

const jobNameFilter = filteredJobName.trim()
const predicates = Predicate.allOf(...[
  (j: Job) => filteredDomains.contains(j.domain),
  ...selectedTagsIds.length() ? [(j: Job) => j.tags.some(t => selectedTagsIds.contains(t))] : [],
  ...jobNameFilter ? [(j: Job) => j.name.toLowerCase().includes(jobNameFilter.toLowerCase())] : []
])

return jobs.filter(predicates)

[emmanueltouzery]

thanks for the feedback! Much appreciated. As you could see, I'm really trying to take documentation seriously.

Every once in a while I look at this equality paragraph in the readme and I have the same thoughts than you, yes. But everytime i end up again thinking it makes sense to keep it in the README. My main worry is that only few people will actually go to read the user guide. I certainly think that equality in prelude-ts is an important topic, and so it should be covered in the readme, however it could be covered in less depth. Probably the bits after "But in some less obvious cases..." can be dropped from the readme, and probably more than that. I'll try and have a go at this one of these days.

Interesting about the wiki. My intention was that users would click the "User Guide" link from the readme (which is bold), it didn't cross my mind that someone would click the "wiki" tab from github. I also added a badge "apidoc available" at the top of the README and was considering whether it would make sense to add such a badge for the user guide too. I'm not sure about making it the wiki home page because maybe we'll want to put other things in the wiki? The wiki url should be stable because it's linked to from the readme, which is visible on prelude-ts's npm page. But just now since we renamed the project the npm page link is obsolete so there is actually a window of opportunity to make it the home page. At the very least we can edit the wiki home to have a nice link to the wiki, but maybe you're right and it should just be the home. I'll think about it as well, but right now I'm thinking maybe in the future we'll want something else as the wiki home page.

Interesting example regarding predicates, but it seems a little long a specific for a user guide. Also, I think predicate is not a central feature of prelude-ts, not central enough to warrant such a space in the user guide at least. Maybe such a large example would be better suited for let's say a blog post rather than the user guide.

[lppedd]

@emmanueltouzery I agree on the fact that not everyone will read the Wiki, but hey, it's their fault if a link is there on the front page. Anyway in the end if you like seeing that on the README, than be so. It isn't a major problem, I'd even say it's not a problem at all (mine was only an observation).

I've seen you have a blog page. Maybe while I use your library I can take some examples out. I'm actually using Map(s) and Set(s) for a Redux State, and I'm using Vector + Option to carry data around. I still have to find an use for Either and Tuple, but they'll eventually be handy.

If you don't mind I have a couple aspects to clarify with you. I'm going to send a tweet as I don't want to open unneeded and unclear issues.

[emmanueltouzery]

Thank you for the feedback! Your points were good, I just need to find the time. I'll be more responsive to questions as they block you. Issues might be a better medium than Twitter for those, but whatever suits you.

I think writing a blog entry is tough, I didn't mean that you'd write for "my" blog, but that you could write yours and I could link and promote it for instance. But I thought your example is a little complex and not self-contained enough for the user guide.

[emmanueltouzery]

I have reduced a little bit the equality section in the readme and added a bold link to the user guide from the wiki main page. I do think both changes help, although I didn't take them as far as you intended. And sorry for the delay.

In the future please don't refrain from opening issues in the bug tracker! They're always welcome!