Repository navigation
Next 10 - Mini summit - Modern HTTP and Documentation #108
Description
Activity
Collaborator discussion as planned - https://github.com/nodejs/node/discussions/41462
Added to the Node.js callendar/
I'll be there
Unfortunately I'll be flying this day and time, and won't be able to make it. Let me know if there's anything I can do ahead of time!
Reacted by Tierney Cyreni will be there
Yeah I can be there
@Trott from the discussions in the Next 10 team so far it's agreed (and documented in https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md) that Documentation is an important part of the future success of Node.js. The goals of the discussion would be:
- Is the state of the current documentation good enough to ensure future success or are there things the project should be doing to improve them?
- If the answer to 1) is that significant improvements are needed, document specific things that we should do to improve the documentation.
Documenting agreement on specific things that are important (and conversely those that are not important) might let us find something actionable that we can do/point people to who have an interest.
Right now I've heard the sentiment that the docs "are not good" but I don't have any insight/view on what specific things we could to do "make them better" or what better would look like. If we believe it's important for future success it warrants some discussion to see if we can document something specific on that front.
In case I can't make it, which is likely, things that could improve documentation, but that also I'm not entirely sure are needed or should be priorities over other (doc and non-doc) things:
- Search functionality (or is Google/Bing/Yandex/etc. sufficient?)
- Automated generation from JSDoc in a consistent format (or is JSDoc not something that provides all the information we need?)
- Separation of "here's the API reference" and "here's a breezy explanation of how to use the thing" (or maybe it's good that they appear in the same place?)
- More consistent layout/organization and editorial voice
- Is the one-page-per-module approach working? Or should we adopt something more like an MDN approach where it's one-page-per-function? (I like our current approach but I find it hard to imagine the alternative so I might not be comparing it against anything.)
- Stuff is in surprising places if you don't know where to look. If I see
process.stdin.unref()in code, I'm going to look in theprocessdoc. It won't be there. If I know a thing or two about how Node.js works under the hood (which I shouldn't have to in order to use the docs), I might look instreamswhere I will also have no luck. Maybe I'd eventually find it innetand wonder why I had to go on the wild goose chase. - Let us please get rid of the knowledge base. Leave tutorials to the community. There are some things in the knowledge base that should be preserved on the site. Let's move them to the docs.
- The team splintering of nodejs.org (website team), docs in core (core team), and nodejs.dev (website redesign team) is a problem. (And yet, is it?)
I'll stop there!
Reacted by Manish Kumar ⛄Welp
What's 10 Eastern timing in terms of GMT?- Reacted by christopheek
I've added a google doc for the minutes here: https://docs.google.com/document/d/1bgXyUCk1n7CRO94lti_oZhqaP366nBrAJJpy0SROMfo/edit#heading=h.arwejbh182t9
Looking forward to seeing everybody tomorrow.
PR to document strategy agreed for modern HTTP - nodejs/node#41798
Going to close this out. We still need to land some updates in the Node.js in terms of what was agreed on the documentation front but I think this does not need to stay open for that.
Reacted by Matteo Collina
Next-10 Mini summit - Modern HTTP and Documentation
When
Thursday Jan 27th
10-2 Eastern
Where
zoom: https://zoom.us/j/99950131676
Agenda
Misc
Will look to promote through