This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Repository navigation
This repository was archived by the owner on Mar 25, 2018. It is now read-only.
add "recommended reading" sections to docs #100
Description
I would like to discuss the pros/cons of having a list of "recommended reading" items at the beginning of a higher-level reference (such as HTTP or Streams) that presents folks with concepts/APIs with which familiarity is recommended to better understand the current document. HTTP, for example, is a high-level core-module that orchestrates many lower-level core modules:
EventEmitterBufferStreamsnet.Socketnet.Server- etc...
So the "Recommended Reading" Section could be:
HTTP
Stability: 2 - Stable
Activity
eljefedelrodeodeljefe commentedon Apr 18, 2016
👍 on the idea. Recommended reading within our docs/guides or external also?
techjeffharris commentedon Apr 18, 2016
Definitely links to internal content, and perhaps links to reliable external sources such as MDN References.
benjamingr commentedon Apr 18, 2016
I don't think it should be per module via "recommended reading". I think inlining them in the introductory section by making every new reference a link (a-la-wikipedia) would be really useful though.
techjeffharris commentedon Apr 18, 2016
You would rather the references be integrated in plain English in the introduction, rather than in a list format, correct?
Sounds to me like you're proposing that we be more liberal with links to external sources like wikipedia, MDN, in addition to internal content, yes?
Knighton910 commentedon Apr 18, 2016
+1 from this guy.
estliberitas commentedon Apr 20, 2016
Agree w/ @benjamingr - it should be some kind of introductory overview pointing people to exact documentation pages or sections in this pages, it makes more sense for anyone who is just starting developing with Node.
And agree about external links. Since we already do it in doc pages (links to man pages or general JS objects like
Error), we can continue pointing people to stuff like MDN, linux.die.net, etc.Talking about format, I'd make several paragraphs with links and after that provide a "Read more" list with link. So idea would be to join ideas of @techjeffharris and @benjamingr
benjamingr commentedon Apr 21, 2016
@techjeffharris
No, I meant to use the same strategy used by wikipedia where terms are linked inline the first time they appear on the page.
Trott commentedon Mar 13, 2018
Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.