Skip to content
This repository has been archived by the owner on Mar 25, 2018. It is now read-only.

add "recommended reading" sections to docs #100

Closed
techjeffharris opened this issue Apr 18, 2016 · 8 comments
Closed

add "recommended reading" sections to docs #100

techjeffharris opened this issue Apr 18, 2016 · 8 comments

Comments

@techjeffharris
Copy link

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
  • etc...

So the "Recommended Reading" Section could be:

HTTP

Stability: 2 - Stable

Recommended Reading

API References

Guides

@eljefedelrodeodeljefe
Copy link
Contributor

👍 on the idea. Recommended reading within our docs/guides or external also?

@techjeffharris
Copy link
Author

Definitely links to internal content, and perhaps links to reliable external sources such as MDN References.

@benjamingr
Copy link
Member

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
Copy link
Author

I think inlining them in the introductory section

You would rather the references be integrated in plain English in the introduction, rather than in a list format, correct?

making every new reference a link (a-la-wikipedia)

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
Copy link

+1 from this guy.

@estliberitas
Copy link
Contributor

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
Copy link
Member

@techjeffharris

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?

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
Copy link
Member

Trott commented 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.

@Trott Trott closed this as completed Mar 13, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

6 participants