clojure / clojure/clojure-site
Make it easier to find destructuring info?
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 259
- Forks
- 275
- PR merge metrics
- No merged PRs in 30d
Description
I love Clojure, but I go through long periods where I don't use it at all. As a result, I repeatedly need a refresher on the nuances of destructuring. Every time I do this, I go to clojure.org and spend at least five minutes poking around and trying to find the page that goes into different ways of using keywords in maps, how to use &, etc. Since this has happened to me numerous times, I've started to wonder whether it would be a good idea to make it easier to find this information.
First, it's difficult to find info about destructuring in the Reference section of clojure.org. It's there under "Binding Forms" (although I didn't find it before I started writing this), but there's no way to figure this out from the top level. There's a page on destructuring in the Guide section, which is great, but since defining functions and using let is basic, core information, I'm going to look to Reference for that first. Of course the Guide on destructuring is less terse and does more hand-holding than the Reference section on binding, as you'd expect, but I don't expect to need a guide for a refresher on core functionality.
Second, in other languages, similar functionality is sometimes called "pattern matching", so when I'm coming back to Clojure after a while away, sometimes that's the keyword I'm looking for. That's not the term we use in Clojure, and I don't think it appears on clojure.org, but it's a reasonable keyword. In my case, I look for "pattern matching", but when I see "destructuring" I know that that's what I'm looking for. Maybe someone coming from another language wouldn't know that? Not sure. In any event, it would be helpful if someone could use that term to find information about destructuring.
Thanks!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Reference section's “Binding Forms” page and the Guide's destructuring page, then inspect how those pages are reached from the clojure.org top-level navigation. Done means a returning reader can find destructuring from the Reference area and can reach it when searching for “pattern matching.”
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100