Meeting #1 about docs

[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.

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

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

[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

[sam-github]

@Trott I agree with you, see #119 (comment). There are doc/guides and doc/topics, and I think there is consensus that info about maintaining the node repo itself shouldn't be on the website, and shouldn't have been called "guides" in the first place.

[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.

[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.

[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.

[Qard]

Yep, that's our feeling too. Contributor-specific stuff can stay in nodejs/node.

[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.

[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

[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.

[gibfahn]

+1 to starting by moving the User Guides in nodejs/node doc/guides to nodejs/nodejs.org locale/en/docs/guides, as there are already guides there, the ones in nodejs/node are just in the wrong place. I think @nodejs/website are the team who manage the website.

---

Also +1 to linking to guides from the API docs where relevant, maybe a link to (e.g.) the timers guide from https://nodejs.org/api/timers.html, and also a general link to User Guides or something underneath Usage & Examples.

---

When I search "node docs" I get the API docs first, but maybe that's because I've used them more often, in any case the overall docs page is second.

[thefourtheye]

Would we be interested to discuss nodejs/node#10726?

[bnb]

Just wanted to note that search results are not always consistent for everyone. There are several factors that determine what show up to each individual. Best way to determine the default is to go into Incognito/equivalent mode and they usually turn up the same.

[Qard]

@thefourtheye 👍 to that idea.

[laosb]

Having a separated guide.*.tld is what big projects usually do. Putting them inside website will lead to confusions. Many would search for guide and they may won't find the Guide hiding in DOCS section, because in many projects they're separated, eg Meteor, RoR, Vue, etc. Obeying a common pattern would decrease the time to understand the website.

[Qard]

Closing now.

We should present our suggested guides markdown location to the CTC. It looks like the consensus currently is to put those in http://github.com/nodejs/nodejs.org. The accessibility issue will need further discussion.

Is that a fair assessment? If anyone disagrees with that conclusion, speak up. Otherwise, I think we can present our decision to the CTC.

[eljefedelrodeodeljefe]

Hmm. I think this doesn't catch the topic completely.

1. Location (as in repository): consensus, not having them in core, and can be nodejs/nodejs.org
2. Location (as in accessibility): no consensus, as every statement above, suggests something slightly different, but I think there is a majority for not putting it in nodejs.org/docs/guides or similar. At least I would strongly oppose this.

[Qard]

Yep, my thought was just to propose to the CTC that we move the code and we can deal with the accessibility concerns later. As I expressed, it seems like that needs deeper discussion.

[eljefedelrodeodeljefe]

Okay in that case. Thx.

[Qard]

@evanlucas Would you mind presenting this to the CTC? Also, do you have powers to add ctc-agenda label to this? The label seems to not exist yet in this repo and I don't appear to have the power to create it.

[sam-github]

@nodejs/tsc Can someone with the power arrange that all doc WG members (https://github.com/nodejs/docs/blob/master/README.md#current-documentation-wg-members) have ability to configure labels and do other routine maintenance of the nodejs/docs repo? @Qard doesn't seem to have that power, ATM.

[Trott]

Of the four guides that are currently in the nodejs/node repository under doc/guides, three of them are specific to contributing to core. I personally think it makes sense to have those with the source code and may not make a whole lot of sense having them on the nodejs website.

[Trott]

@nodejs/tsc Can someone with the power arrange that all doc WG members (https://github.com/nodejs/docs/blob/master/README.md#current-documentation-wg-members) have ability to configure labels and do other routine maintenance of the nodejs/docs repo? @Qard doesn't seem to have that power, ATM.

Need to be added to the @nodejs/documentation group to have those privileges in this repo. I'll add @Qard right now, but if someone else wants to compare the membership of that team with the membership of the WG and provide a single comment (or separate issue) listing members to be added/removed, that would probably be good.

EDIT: Whoops, @Qard is already a member. Either someone beat me to it or I don't know what I'm talking about. (Maybe both, even.)

EDIT 2: Double whoops, you're talking about creating labels rather than applying them. Yeah, I have no idea. I'll create the label though if no one has beat me to it.

[Trott]

I created a ctc-agenda label, but note that the tooling that creates the agenda for meetings won't pick it up if the issue it is applied to is closed. So be sure to create a new issue or re-open this one.

[evanlucas]

I'll open an tracking issue at nodejs/node so we can get it in for the next meeting

[Qard]

Great, thanks all!