Meeting #1

[Qard]

Let's get this async meeting thing started. There's two topics I want to cover:

• Where should we put the guides
• What guides do people want (not necessarily what they personally are volunteering to write, just want to document our current doc deficiencies for now)

Anyone have any input on these topics, or more topics they want to discuss? I'll leave the issue open for discussion for 72 hours to give people some time to comment.

[Qard]

My vote is for guides to be part of the website as they are more abstract than the reference docs and therefore probably don't need as much effort to stay in-sync with the codebase. It'd probably also make translation easier being part of the website. Might be good to get some input from @nodejs/localization though.

As for what guides I'd like to see, some intros to popular routing frameworks and websocket libraries would be good. A guide on making cli tools would also be good.

[sam-github]

Agree, and would like to see these guide-like materials moved from nodejs/node/doc/guides to the Website repo:

• https://github.com/nodejs/node/blob/master/doc/guides/timers-in-node.md
• https://github.com/nodejs/node/blob/master/doc/topics/blocking-vs-non-blocking.md
• https://github.com/nodejs/node/blob/master/doc/topics/event-loop-timers-and-nexttick.md

I also think https://github.com/nodejs/node/blob/master/doc/topics/domain-postmortem.md should be moved to a documentation/Website guide, it includes important information on the limitations of Domains, and gives context to their deprecation.

The other three "guides" in https://github.com/nodejs/node/tree/master/doc/guides are not documentation guides, they are internal docs on Node.js mainteance process and procedure, do not need to be on the website, are not actually "guides" in website/documentation terms, and should be moved up a directory into https://github.com/nodejs/node/tree/master/doc for now to be beside the other onboarding docs.

A case has been made that those onboarding/collaborator docs deserve a location that is not in doc/, which I agree with, its problematic to have things in doc/ that don't show up in the doc website, but maybe one thing at a time, because there are lots of ways of reshuffling those files, but the situation with guides is more clear cut, IMO.

[evanlucas]

I think we should get all guides that are intended for end users of node to the website as well. I think they should be moved to https://nodejs.org/en/docs/guides/ in particular.

I agree with @sam-github that we should wait on the onboarding/collaborator docs and just do the enduser guides as a first step.

[eljefedelrodeodeljefe]

Strongly against putting it on the site as no-one reads it there. At least the link should be prominent in the API docs. Especially the design inconsistency between the sites makes it really unconnected, for visitors.

A good example for structure of docs is Kubernetes http://kubernetes.io/docs/, which makes a mindful combination guides, tutorials, docs, and API docs.

[Qard]

👍 for a clearer distinction between user-focused guides and collaborator-focused guides.

[laosb]

Having a separated guide site like many projects do would be great.

[Qard]

Sorry if it was unclear, but I'm not arguing for putting guides somewhere other than reference docs in terms of website navigation, only code location.

[evanlucas]

Strongly against putting it on the site as no-one reads it there.

@eljefedelrodeodeljefe do you have any data to back that up? It is directly accessible on the page labeled "DOCS" from the website.

[laosb]

I mean, a separated repo and site.

[eljefedelrodeodeljefe]

@evanlucas Of course not. What a question.

[eljefedelrodeodeljefe]

It#s about making good user experience decisions. Simply counting the clicks you need to do to get there, and there prominence on the site is revealing enough.

[eljefedelrodeodeljefe]

@evanlucas Also SEO: goovling for Node docs, brings up API docs first. Please be constructive

[evanlucas]

Googling for node docs brings up https://nodejs.org/en/docs/

If one were to follow the link in the first search result, they are brought to the main docs page that has api documentation for the two latest versions (LTS and Current). Directly below the API document is a link called Guides. I'm suggesting that we place the guides on the page titled Guides.

Here is a screenshot of the docs page:

The list item labeled Guides links to the page that I suggested (https://nodejs.org/en/docs/guides/)

As you can also see from the first screenshot, the Guides link is also prominently displayed to the bottom right of the first search result.

[Qard]

@laosb Are you implying just a different subdomain like docs.nodejs.org, or a fully separate site like rust has with rustbyexample.com? I would prefer a closer relationship with the official website, but I think a separately managed docs.nodejs.org website might be fine. I worry a bit about the extra burden of taking on the website management aspect of that though, which would essentially be duplicated effort from what the existing website wg already does.

[sam-github]

I think this is getting side-tracked. First thing is to get the "guides" that are invisible to our users because they exist only in markdown in the nodejs/node repo onto the website where the other guides are.

I've no objections to rearranging the website, once it has content, if someone thinks they have some constructive suggestions for rearranging it, speak up.

Its not clear to me that the docs WG controls the website, though, or should. At one point, wasn't there an active Website WG? Aren't they still active? @mikeal