Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Next 10 - Mini summit - Modern HTTP and Documentation #108

Closed
4 tasks done
mhdawson opened this issue Jan 10, 2022 · 19 comments
Closed
4 tasks done

Next 10 - Mini summit - Modern HTTP and Documentation #108

mhdawson opened this issue Jan 10, 2022 · 19 comments

Comments

@mhdawson
Copy link
Member

mhdawson commented Jan 10, 2022

Next-10 Mini summit - Modern HTTP and Documentation

When

Thursday Jan 27th
10-2 Eastern

Where

zoom: https://zoom.us/j/99950131676

Agenda

* Modern HTTP - 90 mins
* Break 15 mins
* Documentation - 90 mins
* Break 15 mins
* Wrap up and capture next actions

Misc

Will look to promote through

  • TSC agenda
  • post a collaborators discussion
  • Joe will reach out to Undici team to make sure they can be part of the discussion
  • Reach out to James to see if he can talk about HTTP3/QUIC
@mhdawson
Copy link
Member Author

@ronag you mentioned you would be interested. @nodejs/undici would be great to have other members from the Undici team as well.

@jasnell any chance to are available to help cover HTTP3/QUIC?

@mhdawson
Copy link
Member Author

Collaborator discussion as planned - nodejs/node#41462

@mhdawson
Copy link
Member Author

@joesepi, @bnb any chance one of you two could send out a tweet from the Node.js account to promote participation?

@mhdawson
Copy link
Member Author

Added to the Node.js callendar/

@mcollina
Copy link
Member

I'll be there

@Ethan-Arrowood
Copy link

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!

@sheplu
Copy link
Member

sheplu commented Jan 17, 2022

i will be there

@jasnell
Copy link
Member

jasnell commented Jan 17, 2022

Yeah I can be there

@mhdawson
Copy link
Member Author

@Trott I know you are very active in Docs, FYI hoping you'd want to attend.

@nodejs/documentation, @Trott and FYI to people are are active on docs hoping they will attend.

@mhdawson
Copy link
Member Author

@bnb will send out a tweet to promote from the Node.js account. @bradley will also tweet out.

@Trott
Copy link
Member

Trott commented Jan 19, 2022

@Trott I know you are very active in Docs, FYI hoping you'd want to attend.

Is there more detail available about what aspects of the topics will be discussed? What's the hoped-for outcome of the conversation?

@mhdawson
Copy link
Member Author

mhdawson commented Jan 20, 2022

@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:

  1. 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?
  2. 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.

@Trott
Copy link
Member

Trott commented Jan 21, 2022

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 the process doc. 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 in streams where I will also have no luck. Maybe I'd eventually find it in net and 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!

@thelebdev
Copy link

Welp
What's 10 Eastern timing in terms of GMT?

@targos
Copy link
Member

targos commented Jan 21, 2022

15:00 if I'm not mistaken: https://www.timeanddate.com/worldclock/meetingdetails.html?year=2022&month=1&day=27&hour=15&min=0&sec=0&p1=179

@mhdawson
Copy link
Member Author

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.

@mhdawson
Copy link
Member Author

PR for minutes -#114

@mhdawson
Copy link
Member Author

PR to document strategy agreed for modern HTTP - nodejs/node#41798

@mhdawson
Copy link
Member Author

mhdawson commented Feb 7, 2022

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.

@mhdawson mhdawson closed this as completed Feb 7, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

8 participants