Next 10 - Mini summit - Modern HTTP and Documentation

[mhdawson]

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]

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

Collaborator discussion as planned - nodejs/node#41462

[mhdawson]

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

[mhdawson]

Added to the Node.js callendar/

[mcollina]

I'll be there

[Ethan-Arrowood]

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]

i will be there

[jasnell]

Yeah I can be there

[mhdawson]

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

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

[Trott]

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

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

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]

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

[targos]

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]

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]

PR for minutes -#114

[mhdawson]

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

[mhdawson]

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.