chore(blog): announce documentation redesign - #9167
avivkeller wants to merge 2 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #9167 +/- ##
==========================================
+ Coverage 86.08% 86.10% +0.01%
==========================================
Files 86 86
Lines 6046 6040 -6
Branches 357 357
==========================================
- Hits 5205 5201 -4
+ Misses 837 835 -2
Partials 4 4 ☔ View full report in Codecov by Harness. |
Signed-off-by: Aviv Keller <me@aviv.sh>
📦 Build Size ComparisonSummary
Changes🔄 Modified Routes (4)
|
bmuenzenmeyer
left a comment
bmuenzenmeyer
left a comment
There was a problem hiding this comment.
I know this is draft but thought I'd add some initial thoughts.
I don't know if this voice is exactly what I would choose (things like we love you, but I refrained from flagging too much of it. This is your blog post and you are right to state you had the largest hand in making it a reality.
| A few years ago, [nodejs.org](https://nodejs.org) went through an [extensive makeover](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign). Since then, we have done anything and everything but slow down. | ||
|
|
||
| For the past few years, the Node.js Web Team has been hard at work creating a brand-new documentation design system to complement the overhaul of [nodejs.org](https://nodejs.org). |
There was a problem hiding this comment.
nit: this feels like two intros. Combine
|
|
||
| ## How We Got Here | ||
|
|
||
| Like the [website](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign), we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. |
There was a problem hiding this comment.
suggest omitting this blog a second time (and later a third)
| Like the [website](https://nodejs.org/en/blog/announcements/diving-into-the-nodejs-website-redesign), we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. | |
| Like the website, we've taken great care in approaching and implementing this design. As the saying goes, "Rome wasn't built in a day," and it's important that we highlight the often thankless work of the maintainers who made this redesign what it is today. |
| * A mobile interface | ||
| * A sticky sidebar with reading time, historical information, and a table of contents. | ||
|
|
||
| ## How We Got Here |
There was a problem hiding this comment.
I think this could be better explained with some of the content from the doc-kit talk, where we work through the timeline of constraints and consensus at the outset, ever-expanding feedback loops, like-for-like experience first, beta, etc.
|
|
||
| This was largely due to a few key issues: | ||
|
|
||
| 1. There was no [first-party way to search](https://github.com/nodejs/node/issues/31598) the API documentation, and external search engines could provide [contradictory or mismatched information](https://github.com/nodejs/nodejs.org/issues/6577). |
|
|
||
| ### Working Backwards | ||
|
|
||
| Unless you have brainpower far exceeding the entirety of humankind, there is no practical way to "visualize" an abstract syntax tree. |
There was a problem hiding this comment.
This is sorta odd of a statement. You might be better off actually showing a short AST for something like
console.log(`hello {name}`)
|
|
||
| Once we had that foundation, the next step was the two-month-long PR adding the [`web` generator](https://github.com/nodejs/doc-kit/pull/285), responsible for taking the generated JSX, bundling the required components and JavaScript, and producing the redesigned static documentation pages. | ||
|
|
||
| ### Refining |
There was a problem hiding this comment.
I think this could be better explained with some of the content from the doc-kit talk, where we talk of ever-expanding feedback loops.
|
|
||
| ### The Redesigned JSON Generator | ||
|
|
||
| A [redesigned JSON generator](https://github.com/nodejs/doc-kit/pull/1079) would allow us to create a more deliberate, documented, and extensible representation of the Node.js API, particularly one that allows consumers to easily parse Node.js types, descriptions, and other details. We plan to work closely with the [`@types/node` maintainers](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node) to create a JSON format that allows consumers to learn all the same information available visually, in a more machine-readable format. |
There was a problem hiding this comment.
IIRC, the types/node folks didn't seem to care too much about this.
2 participants
(Blocked by the release of Node.js v26.10.0)
https://nodejs-org-git-doc-redesign-openjs.vercel.app/en/blog/announcements/new-docs-site