i18n initiative documentation

[sheplu]

Most of the language and framework now have a documentation translated in multiples languages allowing newcomers an easier / simpler way to onboard with the language.

Node.js seems to be on of the top technology not having that (I will provide an updated list on technologies and framework) and I think it would be nice to provide this functionality on the documentation

There is currently a crowdin with allow people to provide translation in a good / easy way but I don't think this is included on the new website initiative / new changes (I will check)

It could be great to discuss about that in a later meeting

• do we want to provide that?
• if yes which language
• how we want to do it
• on which part

[ovflowd]

Hey there, @sheplu 👋 , indeed Crowdin is not included in the new Website initiative. I would love to sync with you regarding what you need from our side to make it work, or even what the options would be.

[sheplu]

hello @ovflowd !
I opened the issue mostly to start a discussion about i18n for some/all resources regarding Node.js.
I don't really have a preferred tool but mostly would like to see if we want (I think that could be great) to work on this topic

I am not sure who is running the crowdin or if there is some activity on this part but we can talk about it and try to see what we can all do !

[ovflowd]

Would love to talk, I'm on Slack 🙃

[ovflowd]

Meeting notes:

Different kinds of Documentations

We discussed that what we understand as "documentation" is a collection of living documents that embrace three different primary embodiments, those are:

• API Docs: A bare-bone visual representation of the specifications of the set of APIs exposed by Node.js. From classes, modules, functions, constants and more. These primarily should be auto-generated.
  • One of the ideas here is to pick the source from the JSDocs directly. (Idea!)
    • Simple examples and descriptions are provided within jsdoc
    • Snippets are a pure code-only snippet
    • Descriptions can be translated through locale files
• Node.js Docs: Actual human-focused documentation about the modules that Node.js provides
  • Actual Markdown files (MDX) that describe and guide through each Module of Node.js
  • Separated by categories, where each page is about a module. (Idea)
    • Pages have tags that are handy for when searching for content
    • Each page explains what this module is about, what it does, and gives examples and repl.it (Live snippets that users can play around)
  • These docs get versioned per Node.js release (Idea)
    • eg.: content/docs/16/fs.md
    • This allows examples and functionalities of that module to be introduced and explained by relevance (Eg.: v18 introduced XX on fs)
  • Each doc has an introduction section independent of the Node.js release. (Idea)
    • Allows a generalised introduction
  • Docs pages have a table of contents
• Learn & Guides: These are guides that introduce you to the Node.js world
  • Learning guides are separated into sections "What is Node.js", "Getting started", "Introduction", ....
  • Learning guides explain real-world scenarios for what you can do with Node.js, eg.: "How to make a web server", "How to read & write files", "What is NPM"
    • Each page also has tags that allow easier indexing/search
  • Learning guides focus on introductory and essential guides for the Node.js world. They might also enter the world of some more intermediary examples, but the idea behind these guides is to give you an insight into what you can do with Node.js; they're not meant to be actual courses or deep-dive learning materials.
  • Learning guides are not-versioned and should resemble the state-of-art of Node.js

How we provide Documentation

Interestingly, creating such Documentation standards is a no-easy task. Generating the API Docs and rendering them into a Website (in a format that is accessible, localised and easy to search and navigate) is the bare-bones of requirements. Yet, these are easy once a standard is defined (e.g.: generating from jsdoc).

Creating Node.js Module Documentations (Node.js Docs) requires contributor effort from migrating from the current docs provided in the API docs to content that suits such section and is a long-term effort.

• Indexing the content and making it available (Currently working on nodejs.dev)
• Able to create custom labels for each page (Needs Refinement)
• Support current Docs from node/docs/api (In Progress on nodejs.dev)
• Localisation of Learn guides and Node.js Docs (Currently working on nodejs.dev)
• Generation of API Docs from jsdoc (Needs significant discussion with Docs/Build/Release team)
• Definition of Specification/Standard for Docs in the future (Needs significant discussion with Docs/Build/Release team)

[sheplu]

thanks a lot for the full meeting note @ovflowd :) it was really great talking to you !
I will try to join for the next meeting around nodejs.dev as a lot of works seems to be already in progress.