overlap between 'Language: clojure.core' and 'Language: Collections and Sequences'

[bobisageek]

I was looking to do a little 'polishing' (typos and stuff), and I noticed that these two pages seem to have a fair bit of overlap, not only in the functions they cover (which kind of makes sense), but also in that a significant portion of those overlapping functions have nearly identical content.

As one example (of many), the conj entries are mostly identical, with an extra sentence at the beginning of one

clojure-doc.github.io/content/md/articles/language/core_overview.md

Lines 568 to 590 in 295fb60

	### conj
	```clojure
	([coll x])
	([coll x & xs])
	```
	`conj` takes a collection and a variable number of arguments.
	`conj` is short for "conjoin". As the name implies, `conj` returns the
	collection with those arguments added.
	Adding items to a collection occurs at different places depending on
	the concrete type of collection.
	List addition occurs at the beginning of the list. This is because
	accessing the head of the list is a constant time operation, and
	accessing the tail requires traversal of the entire list.
	```clojure
	(conj '(1 2) 3)
	;; ⇒ (3 1 2)
	```

clojure-doc.github.io/content/md/articles/language/collections_and_sequences.md

Lines 518 to 530 in 295fb60

	### conj
	`conj` is short for "conjoin". As the name implies, `conj` takes a collection and argument(s) and returns the collection with those arguments added.
	Adding items to a collection occurs at different places depending on the concrete type of collection.
	List addition occurs at the beginning of the list. This is because accessing the head of the list is a constant time operation, and accessing
	the tail requires traversal of the entire list.
	```klipse-clojure
	(conj '(1 2) 3)
	;; ⇒ (3 1 2)
	```

I don't want to say that covering the info multiple times is totally a bad thing, but what comes to mind is that if you read both pages, you get a sense of deja vu, but the pages don't cover all the same content, so if you don't read both of them, you might miss info that's covered in the difference.

I don't have any specific 'ideal answer' in mind here, but I would sort of like to work on these pages, and I wanted to have the discussion about a tactic going in.

A few possible approaches that come to mind:

• do nothing - leave the content as is, and make the 'polishing' consistent in both places
• consolidate overlap on clojure.core - core page maybe gets longer, collection page probably goes away or maybe just has descriptions of collections and sequence types (and maybe a section on clojure.set?)
• consolidate overlap on collections page - core page gets smaller and probably links to the collections page, but might change the feel of the core page a bit, because so much of core is aimed at collections/seqs, so it sort of becomes 'core minus sequence-y ops'

Is there a preferred approach/vision for these pages?

[seancorfield]

I think I would lean somewhat toward bullet no. 3 -- leave the functions in core with minimal description (and maybe a basic example) and link to the relevant collections page "for more detail and (further) examples".