-
Notifications
You must be signed in to change notification settings - Fork 31
add "recommended reading" sections to docs #100
Comments
👍 on the idea. Recommended reading within our docs/guides or external also? |
Definitely links to internal content, and perhaps links to reliable external sources such as MDN References. |
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. |
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? |
+1 from this guy. |
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 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 |
No, I meant to use the same strategy used by wikipedia where terms are linked inline the first time they appear on the page. |
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. |
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:
EventEmitter
Buffer
Streams
net.Socket
net.Server
So the "Recommended Reading" Section could be:
HTTP
Recommended Reading
API References
Guides
The text was updated successfully, but these errors were encountered: