add first draft of ROADMAP.md

[chrisdickinson]

Here's a first draft of the roadmap for @nodejs/documentation to discuss!

[chrisdickinson]

"Overview" might be a more descriptive term for this kind of documentation than "Topic."

[Knighton910]

💯 Nice

[thefourtheye]

This has to point to website

[thefourtheye]

Node.js

[eljefedelrodeodeljefe]

I have no big stake in it, but I think not having some features as e.g. the es-switcher thing nodejs/node#4915 could work against this. Having a look at newer project's docs they are all the same and imo lack e.g. interactiveness. Sorry for bringing that up. Couldn't read up on the wg meeting yet and also couldn't participate.

[chrisdickinson]

No apologies necessary — it's totally my fault. Sorry for dropping the ball on getting that resolution out to where it needed to go. I'll make sure it doesn't happen again. I'm going to start an issue for the next meeting today, which was scheduled for Wednesday at 10AM PST next week. We can definitely revisit the timing of meetings along with that, since there are so many new members.

With regards to interactivity, it can be a double-edged sword. In the ES2015/ES5 switcher case, it's fine to use on the website's front page because the number of code examples there are bounded, as time goes on they can replace ES2015 with ES2016 and up, and due to the smaller number of examples, they can more easily curate that content.

Applying the switcher to the docs is a big maintenance load: it can grow on the axis of number of language versions to support, it can grow on the number of code examples in the docs to be translated into different versions, and because it affects all code examples, it's represents a significant source of churn on the docs.

The most limited resources the Docs WG have are space and volunteered time. Features that cause a lot of churn stand a high risk of blocking other work because the docs are a relatively constrained space. Maintaining separate examples — or being blocked by churn created by maintaining separate examples — spends volunteered time. Anything that takes a lot from both of those resources has to pay back that debt either by making it easier to work on the docs or by greatly increasing value for readers. Because the switcher represents a continual investment of author effort, it can't do the former, and because it doesn't offer any explanation of what the user is switching between, the value offered to readers is marginal — they would likely be better served by us redirecting them to a separate "learn javascript" document, either written by us, or maintained elsewhere (like jsforcats, or mdn.)

More generally, features that greatly increase the usefulness of the docs for readers while not continually spending author time are a net win. Some of the features proposed in the ROADMAP, like per-section YAML containing version information, represent a significant investment in churn and author time, but for the most part it's a one time cost. The ongoing cost can be mitigated by creating an automated linter rule to detect the absence of necessary information, which further reduces the time commitment. Meanwhile, version information is very valuable for users — they can now see at a glance when a feature was introduced, which lets them know immediately if it's available to them for use.

[eljefedelrodeodeljefe]

Okay. Good points Chris. Thx.

[kahwee]

I can help with the following:

• HTML layout for guide docs
• HTML layout update for API docs to include refs to guide docs

I can do the UI which should take cues from work what @Qard and others did for the remark plugins. Is there already some idea what sort of docs layout we want?

[eljefedelrodeodeljefe]

I could offer this nodejs/node#4747 if wanted. This needs string consensus though, because of the implications for the git tree.

[MylesBorins]

I'm interested in documenting this. Currently I'm digging through how "process" gets created

[chrisdickinson]

\o/ :confetti_ball:

[chrisdickinson]

Thanks, all!