Node Collaborators Summit - Berlin 2018 May 31, 2018
Tierny: We’d like to improve the Node docs, and this includes work on website redesign and i18n. The docs experience isn’t great, we need to improve this. We should answer questions like how does Node work? How do we fix bugs on Node.
Adam: To keep this focused: we’re not talking about content for getting started on website or user persona stuff; that will be later today. For website redesign, we’re trying to keep everything focused using normal product lifecycle processes: first, planning and implementation (wireframe, voice and tone guidelines), finally entering the UI phase, to build out the design system and guidance for the Node website. The goal is to keep the progress on this asynchronous and cohesive—and for the design guidelines to last from now until the end of time. Our focus is on high-fidelity design and content. On the topic of content, how much do we want to talk about the community and development in general—i.e. do we have an express example?
Ben: I18n: Zeke has done some awesome work to pull in Markdown files, by the way.
Zeke: To elaborate on that, we have a tool which takes Markdown doc files for major versions, Node 6, 8, 10 (with plans for .x versions), to generate our documentation pages. The goal is to have a Node module to take the docs and automatically internationalize documentation for the new site.
Zeke: On the question of where do we talk about Node and all of development in userland? For background: I work at GitHub on Electron. We could have a page that tells the basics of how Electron works, but you need dozens of modules to get a project off the ground and that exposes a lot of complexity to a beginner. A separate problem we have is we don’t want to play favorites but we want to highlight modules that allow people to hit the ground running.
Adam: Not endorsing specific modules, probably, but maybe we should have a guide that tells users how to npm install something.
Tierny: Is npm installing endorsing a specific module, though?
Tracy: It’s going to be challenging, since we’re very small group of people working on these docs. We’ll want to keep the content very focused. In my experience, when we made the exam, we tried to avoid pulling modules in at all since they were confusing but also to avoid cheating (people could use published modules to avoid writing the code we were testing them on).
Adam: Presumably all the documentation is open source, so new package managers could add to the docs!
Tierny: We’re also totally happy to allow people to contribute their own stacks. Getting started with Stripe or OAuth—major things that use Node a lot. The Node site is not picking favorites (anti-trust stuff considered) but if you build it, maybe people could feel free to contribute it to our guides.
Addison: Coming from the Drupal world, we had a wiki and a central guide curated by us—one section stating this is what we officially support, the other is clearly provided by the community.
Adam: One problem we have is not endorsing a specific technology (yarn, npm, etc). Another problem we have is to provide complete examples, but we run into the Drupal problem where we have to maintain these docs, and any new ones, indefinitely.
Zeke: Are we operating under the assumption that this will all be written in nodejs/node?
Tierny: We’ve gotten a little sidetracked, this is all the content that would live under the guides. The Stripe tutorial would live under that. Installing a module, would live in guides. How to use Node streams would be under Node docs, however. nodejs/node lives in the core repo itself, and ships with Node. You can pull up the docs anywhere you have Node installed. There’s different processes—for example for internationalization there’s a set of bots that need to get run to produce docs for different languages.
Rich: By the way, let’s enable that bots plugin after this is all over.
Tierny: The actual content itself, for example, to have a linter on the docs—check for 404 errors, check for a code example for each API example…
Adam: Do we have docs coverage metrics?
Rich: I’m not clear on what that is? So probably not. (Laughs). There’s a Markdown linter, for example that we use.
Adam: A rule to check that there’s a dot in your Node.js string…
Rich: There’s not a rule but there should be one for that.
Adam: Add a linting step that makes sure that ensures all the code is runnable (for RunKit compatibility). Have people seen the prototype of new docs that Francisco built using RunKit for runnable Node examples?
Francisco: (Demos RunKit docs page) These are the existing code samples, with no modifications.
Rich: We come up with these examples, by the way, from extracting the code examples from the C++ doc.
Domenik: For the RunKit examples to work, I guess you would also need to make sure there are console.logs to output stuff?
Francisco: RunKit works like a REPL so the result of the last line is output directly underneath the code snippet when it’s evaluated. Also it’s worth noting that we currently support all the major releases of Node. If people think it would be useful, we could start supporting the Node nightlies, too.
Tierny: Docs are usually the last thing that happens, so may not be necessary to support Node nightlies.
Zeke: Is there a current pattern for the code samples RunKit uses?
Francisco: We just made it so that all the existing code snippets use javascript runnable and then the Markdown parser replaces that fenced code snippet with a RunKit Embed. This means it degrades gracefully if you have JavaScript disabled in your browser and fallbacks to javascript rules for syntax highlighting.
Adam: Does that mess with Markdown parsers?
Francisco: Nope, we just add a new tag to the JavaScript fenced code blocks (“javascript runnable”).
Tierny: One of the things we’ve wondered is, what if there’s no JavaScript on your browser? (I already know the answer to this, but to demonstrate it for everyone here). Does it degrade gracefully?
Adam: LinkedIn’s firewall blocks RunKit for some reason and I could still read everything just fine.
Francisco: This is what it looks like without JS enabled. (Demonstrates two-column documentation example). Exactly the same as today.
Adam: If not better, since you’re not scrolling as much.
Zeke: Is anything in progress for tutorial documentation?
Adam: Not yet. Which means everything will have to be done from scratch, including localization.
Zeke: We support GitHub-flavored Markdown (GFMD), and yaml in our plugin. If tutorial content doesn’t live in nodejs/node, we need to make sure it’s versioned somehow.
Tierny: We should make sure it’s versioned, somehow. Tutorials should be ported to future versions of Node, but scoped appropriately if an example doesn’t work on old versions, for example.
Rich: The API reference tracks closely with Node versions, but the guides tend to be written and forgotten about.
Addison: Writing docs is not the problem, maintaining docs is the problem.
Rich: We can tag suspect yaml files as things likely to change across Node versions to help with that.
Tracy: When you go to look for content, I’m sure there’s a lot of vendors that would be willing to contribute content too.
Thomas: It would also be great to have some sort of user feedback mechanism. Maybe a CMS system for people to edit content?
Adam: We have a large community, so we can leverage people to fix mistakes on GitHub.
Rich: We should have an edit this page on GitHub button so people can correct these bugs.
Domenik: We looked at this on Twilio: people don’t really read the prose, they just copy and paste the code examples.
Adam: We can certainly get that moving for the tutorials section, add a test case for whether example code is actually runnable to the test suite.
Tierny: We should also think about ways to keep collaborators engaged. We could basically message previous contributors when new versions of Node are released or the examples break linting in the future and invite them to fix these errors.
Domenik: Microsoft and Twilio do this thing where the names of the contributors are shown on the docs pages. That sort of inspires people to contribute.
Tierny: I feel ineffective when editing the docs. The Markdown files aren’t really modular, there’s no consistent rhyme or reason to the files.
Rich: It can be more intuitive.
Tierny: We could definitely make these more modular—buffer could be one module, and everything related to buffers could live together.
Zeke: For Electron, we decided our docs are the source of truth for the Electron API. We made a linter to make sure that for every API change has a corresponding entry in our docs. We produce a JSON blob to show this mapping between API and docs. Our docs were built off of Node’s docs, so theoretically we could modify our tools to work with Node docs.
Adam: What’s the structure?
Zeke: It’s huge—I think 40mb. The structure is a big JSON object, top level keys are languages, and under each language is a key for the file name.
Adam: We’ll probably want a file per language, so you can just load a language pack.
Zeke: Yeah, I definitely want to design the schema with the website in mind, so we can use it for everything.
(discussing details of the JSON structure)
Rich: There used to be a documentation working group, it no longer exists, but the GitHub team is still there, so if anyone wants to join this team, they should. You’ll get a lot of GitHub notifications. This was an official WG, but it got de-charted because the work was “completed.” There’s surprisingly little benefit to being charted, so that may be why it was de-chartered. There’s tons of working groups that aren’t chartered, so don’t let that stop you from feeling you can be super effective on this team!
Tierny: One thing I want to talk about is linting: we have a whole list of things (final new line, JavaScript capitalization). Bigger things like Code blocks. The docs read as though they’re written for Node Core and no one else. When I was trying to get into Node at 0.8 and 0.10, I couldn’t work through the docs. It’s gotten better, but we have a long way to go. If we can make them more friendly to beginners—like code examples that work. For example, there was a method that someone asked about, and I went to the docs and they link to another example which has another unrelated snippet with the actual method I wanted to use. It took three clicks to get to a working code example and it was in an effectively unrelated section.
Domenik: The docs require way too much knowledge of underlying processes. Like knowing exec in spawn, if you don’t come from a Linux world, you might not know what these are.
Rich: Even if you come from the Linux world, these aren’t the same, which is confusing.
Francisco: Something I would like: reasoning or history in the API docs. You look up readdir and readFIle, you look and see all the Stack Overflow questions about why the d in readdir is not capitalized, and that history can be useful to the user rather than appear to be completely insane.
Domenik: Or fstat, like this is a very useful thing in Linux, and that context is interesting to people.
Zeke: On some pages you need to spend 10 minutes on a page when 10 seconds should be sufficient—like the URL page. A probot may be helpful here, “you added all this documentation, but an example would be really nice.”
Rich: Like, If there’s x number of lines of prose, maybe we should require a code example.
Adam: I think we need to consider our target audience for these docs. I would never send someone who’s inexperienced to this API page. This page can definitely be made better (more examples), but how can we make these more accessible to new users? I see three kinds of pages here: these tutorials/getting started, the module documentation, and some references.
Ben: These things need to be more compartmentalized, so someone who just wants reference documentation will reference that.
Adam: As we think about how these Node core docs can change, we should make sure not to exclude these kinds of users.
Tierny: When I was talking about code blocks, that’s what I’m talking about. For new users, being told go read the docs is not helpful.
Adam: What is the JSON structure of the current documents?
(discussion about how the docs JSON is generated and whether it’s used in any official context in Node)
Adam: It could be used as a searchable API interface for our API docs. For example, when you’re browsing the docs in English, we’d load that the API docs in JSON for English and you could search to filter sections that match your search terns.
Francisco: As a third-party consumer of the JSON format of the existing Node docs, RunKIt uses it to show Node documentation in a stack trace. (Demos RunKit stack trace debugging)
Tierny: (Referring to code in nodejs/node repository) Oh, the JSON file is just linked from the docs repository! It’s right there.
Zeke: If we wanted to think of linter specifications from a high-level, how should we go about it?
Tierny: In my opinion, (not to be treated as final!), we should have rules and automation for things like “this documentation needs a code example” so that newer people are required to follow these standards. New people then automatically do the right things from the beginning and are actually helping out from that first experience/touch. This also means we don’t need to dig into new contributions as much if they pass our test suite. One of the implementation ways that I’ve been interested in is Danger Systems (danger.js) or Probot, something we can figure out. We can go in and reduce our burden around maintaining docs, so if we automate this we can make our lives a lot easier.
Zeke: Are you talking about new contributors or maintainers?
Tierny: I’m talking mostly about bots that make it easier for people who are consistently maintaining Node.
Zeke: What is the current maintainer burden for documentation now?
Tierny: Rich, correct me if I’m wrong, but it’s a very manual process; when docs ship we have to do a lot of manual checking. We have the Remark stuff, but we have to check does this code work? Docs shouldn’t necessarily be the last step in the process. Not “oh, god, docs!” but something more friendly and approachable. Automating away a lot of the time-consuming bits helps Node contributors a lot.
Tirel: It’s hard to comprehend how to even write the docs—Markdown and yaml, it raises the barrier to entry. Not just on the writing/prose but even the way to write docs.
Tierny: We need meta-documentation—we need to document how to write documentation. (Laughs).
Rich: The experience around doc PRs is exhausting. We need to make this easier. Someone earlier asked what the linter rules are: this is the npm package: remark-preset-lint-node.Franziska: Watching someone in a video or reading our style guide would make this a lot easier.
Zeke: In Electron, we have a linter, where you get a red “x” on the screen if your documentation fails tests, but you have no idea what specifically is wrong, so you have to go in and investigate. We built a bot CI-reporter that posts a comment with the specific error, but it’s still tough to discern. Part of me wants to move this all into the CI phase/linting phase, to really remove maintainers from the equation.
Adam: Is there a Prettier for Markdown?
Domenik: Prettier supports Markdown.
Rich: Sometimes though, you fix one rule and it breaks another.
Domenik: Knowing where fixing is appropriate is also tough. If you see a typo, that’s obvious, but if there’s a less obvious thing it may be completely missed for a while.
Tirel: This is all concentrating on first contributors, but a system that would ping contributors would be really nice. There’s a real job of keeping people engaged once they’ve contributed. There has to be a way to keep people contributing.
Thomas: Acquisition is always harder than retention.
Zeke: Do we have any analytics on this?
Rich: Greg can tell us.
Zeke: Specifically, what pages are most popular.
Rich: While we get Greg, let me mention that there’s some things that always bother me. Like a dash and emdash. They’re almost always used incorrectly in our docs!
Adam: About emdashes: that kind of thing would be awesome to keep in a voice & tone guide. (Github URL coming). Something we’ll probably have to hand-validate, since it’s hard to lint language.
Rich: We can probably add a rule against emdashes though! Just throw an error whenever one is detected. (Laughs)
Thomas: emdashes sometimes have a use!
Ben: Did we come to a consensus about having all our documentation live in nodejs/node?
Rich: Well it currently lives in nodejs/node…
(Greg enters the room and starts to present Google Analytics pages)
Tierny: Guides are the most popular…
Tracy: Does it make sense to keep the docs tied to release version when they’re not necessarily related to specific version changes? It’s hard to see the overall analytics trends for specific documentation across languages/versions, since they’re all forked at the Node version and language.
Rich: There’s reasons for either way.
Tracy: This means we’d be contributing and updating guides for old versions of Node?
Pieter: We could tag the guides with semver ranges for supported Node versions, so that guides can exist in a directory structure in an engine independent way, but not be rendered for incompatible Node versions.
Tierny: The two most popular paths are /dist/api and /docs. Top most requested pages are fs, http, child_process, stream. path is number 9…
Zeke: For the people that haven’t spoken during the meeting so far, is there anything you wanted to discuss? What are people’s motivations for attending this meeting?
(Silence)
Adam: I’d love to get resolution on where these tutorials live.
Addison: Let’s put this all in the repo, for tracking purposes.
Tierny: Is there anything you’ve heard/discussed that you’d like to contribute to?
Seandon: I’d like to contribute to improving analytics for Node documentation.
Zeke: Bots
Rich: Bots are easier than plugins, since we have a policy for bots.
Zeke: If there was a danger bot or a probot, we’d also have to host it.
Tierny: Getting this solved is a priority for this meeting.
Adam: Can we get that addressed in an ad-hoc session during this summit.
Rich: If anyone wants to help with this, definitely let me know!
Rachel: I’m good at building bots!
Franziska: If we want free compute credits, let me know.
Rich: We’ll get a group going, and hash all this out.
Tierny: Thanks everyone!