-
Notifications
You must be signed in to change notification settings - Fork 29.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Redesign of the Node.js API Docs #52343
Comments
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
Can we move the external dependencies and tools to a different repo, and only keep the markdown documents in this repo? I imagine the new dependencies and build process could make the already flaky CI even more flaky and complicate releases and backports further if they end up in this repo (my brain already starts to hurt when thinking about backporting the tool changes to v18 and then make the addon docs build on SmartOS). |
That is definitely doable. Didn't add to the initial proposal as Im not sure how the feeling/consensus about this one would be. But I definitely would say a +1 to have the tooling somewhere else. The only issue is, generating the docs is part of Node.js build process (Makefile) so Im not sure how we should handle that transition? Would node core need to depend on another node repository and add it as part of the build process? That is currently out of my expertise but I can definitely 👀👀 into it! |
+1 for proposal |
this would be possible either with direct github install instructions or npm publication - both pretty strightforward |
We can still keep a basic renderer here just to make sure that the docs are parsable, and also we still need to generate addon tests from addons.md. |
@ovflowd I think docs must "render" in the browser without JS enabled. Ideally no per-page JS. |
Definitely agreed here, IMO output of both should be a 1:1 match. |
Not sure if this is the right place to mention it, but during the summit I think several people mentioned in different sessions about our docs being too intimidating to beginners - I think by that they mean, API docs are like a dictionary, and you don't learn a language by reading a dictionary. We should have more tutorials in the docs before branching into the API dictionary. Which may affect the redesign because the page layout and information architecture etc. need to consider this. |
I believe that's why we're cultivating an improved Learn section on nodejs.org :) I believe the API docs should be more an API reference, but agree they could be rewritten, improved, and have more examples... But that's not the scope of this issue. |
https://documentation.divio.com/ is an interesting POV on documentation -- our API docs fall into "reference". The main point being that there are different types of documentation and documentation is clearer if those are not mixed together. |
(Removing label
node-api
|
Right, I believe my goal here is just a redesign. I do agree that content-wise our API docs should fall into "Reference" documentation; And we should write Learn material (on the Node.js Website) with actual learning materials for our API Documentation. This is possibly something we want to invest time into. For example @JakobJingleheimer was working on learning material for Node.js Loaders :) |
Indeed 🙂 the first draft is nearly ready (have to first write a package to facilitate an important use-case needed in thr article, which is nearly ready). |
Hey, @nodejs/tsc I'd like to pin this issue, due to its high-visibility and impact on the project. Throughout the years, one of the most common "feedback" factors we've received on social media have been the current state (design) of the API docs; I believe as we're ramping up to work on this enormous piece of work, I'd make sense to highlight the visibility of this issue:
|
Pins are typically used in order to catch cases we have breakages/bugs in order to prevent users from opening duplicate issues. I'm not sure what pinning would accomplish here? |
We have an update: We finally started the work on the new API Doc Tooling, and it's getting nicely done. The initial PR (nodejs/api-docs-tooling#33) allows us already to have a fully working parser for the API Docs and will enable us to start the following work to add the HTML and JSON generators. |
We've landed the core of the new API doc tooling and are proceeding with the generators that will allow us to achieve what we need. |
We've landed the CLI pieces of the new API doc tooling. We're moving forward with implementing the generators that allow us to generate the JSON, HTML and whatnot outputs of the API docs. You can try the CLI already by doing: npm i -g https://github.com/nodejs/api-docs-tooling/tarball/main Then clone And then run the api-docs-tooling -i /path/to/node/node/doc/api/http.md -t json-simple -o . Note that this is all alpha; there will be many changes yet! Also check |
As nodejs/api-docs-tooling#55 is getting closer to land and @flakey5 is going to work on the JSON generator; I believe we should soon start seeing how we'd replace the current code within |
FYI the legacy HTML generator for the new API doc tooling is ready and feature complete nodejs/api-docs-tooling#55 |
FYI the JSON generation is about to get merged nodejs/api-docs-tooling#142 which was the last blocker. We can officially start working into sunsetting the current tooling and integrate the new one on nodejs/node. cc @nodejs/collaborators and @nodejs/tsc for awareness as I'll be possibly soon start drafting a PR that replaces the tooling (and update the contributor docs regarding how to generate docs) |
Hey, y'all 👋 with the redesign of the Node.js Website done. We're ready to move our efforts into revamping the design of the Node.js API docs and its build process.
We understand this is code owned by Node.js Core, so we're (@nodejs/web-infra) opening an issue here.
Overview
Revamp of Tooling
nodejs/nodejs.dev
repository as seen here and hereReactDOM
(Server) to compile the JSX into plain HTML (initial rendering), which is then embedded in the HTML templates, making each page an HTML file. (Source MD file -> Target HTML file as it has been done so far).js
filequery param and hash
to signal to the Browser that these are different versions.out
folder (as described on themake-doc
Makefile step of the Node.js build process)Tooling Dependencies
preact
as a JSX library (+ DOM rendering) since it's pretty much React but lightweight, it has pretty much 1:1 to React's API, and since the API docs are extremely simple statically generated page, we don't need anything fancierVite
for the build process, transpiling/compilation and output to HTML files, and for the availability of HMR/Dev Server. This will be an experiment.MDX
to parse and transform the markdown into MDX/JSX.semver,
might be needed.Revamp of Design
After the revamp of tooling is done, we have a 1:1 feature to the old generation of API docs, and we can generate the same API docs with the same styles, same layout, and same components (the HTML snippets transformed into React Components), we can proceed with the revamp of styles.
This means we would adopt these designs based on the Node.js Website redesign into the API Docs. These designs may still change and are pending @nodejs/tsc approval)
This part is blocked by the monorepo transformation of the Node.js Website repository, which would allow all the existing components to be bundled into a UI components package.
We aim to use Shiki as we use on the Node.js Website for the CodeBoxes and Tailwind and Radix UI for Component tooling and a11y as we've done on the Node.js Website.
This would fundamentally course-correct the current design of the API Docs. Note that we aim to add a Search box (as we've done on the Node.js Website) and restructure the API Docs as described on this initiative of the Next-10 initiative.
It is part of the redesign of the Node.js API Docs:
nodejs/nodejs.dev
tooling attached above as a reference)What is this issue about?
Keeping track of the efforts, communication, feedback, and progress of the revamp of the tooling and redesign of the API Docs is a sort of "Epic" for the whole initiative.
What's next?
Gathering initial feedback, consensus-seeking with Core Collaborators, and starting to delegate work on both fronts. Any support is welcome.
F.A.Q.
Are we going to translate the API docs?
No. It's an impossible and unmaintainable task. There is too much risk and work, and API docs get outdated fast. There is no merit in translating the API docs.
Can I help with the work on the API docs tooling?
Yes and no. We're more than open for feedback, ideas and code review, but the big chunk of work will be done by the Web Infra team which has a good knowledge of the tooling changes needed to be done and a good envisioning of what should be done.
Can I help with the redesign?
Yes! Implementation of components, designs, etc, is more than welcome! The actual components will reside on this repository and the Node.js Website. The API docs will only import the components/use them as the source will be on the Node.js Website repository.
Is there any timeline?
Not yet. We want to reach a consensus first and have a good understanding that the overall community is happy with these proposed changes + the proposed dependencies we want to use, such as MDX.
With MDX are the source files changing?
No. The transform into MDX will happen only in memory during the build time as a build-step. So that we can transform the non-conforming YAML metadata into something React can use. The source files will be untouched.
What are the problems with the current tooling?
The text was updated successfully, but these errors were encountered: