How do you manage to have such nice, consistent README's?

[tefkah]

Hi!

First off all let me say that I'm a huge fan of the unified project and so happy it exists! Managing to create such a rich, interoperable ecosystem of reliable, fun to use tools is such an impressive achievement, truly hats off!

One particular thing I'm really impressed with is the reliable, consistent style of your README's. Having them all be in the same style makes it so easy to pick up a new plugin/util, love it! Of course, I'm not that surprised that you are good at crafting Markdown files, but I am curious as to how! I've looked far and wide but couldn't find any documentation or hints of the tooling used to create them, which finally lead me to just ask: is there any specific custom processor/CI you use for the README's?

I ask because I've been working on some unist/xast compatible tools over here for converting to/from/between .docx, JATS XML & LaTeX (although nothing is in any state to brag about yet 😅). I'd like to keep in line with the excellent precedent of your README's, but I thought that instead of chasing your style/methods I thought I'd first ask whether you haven't published this anywhere!

I'm aware of most of the separate components used like remark-usage but I'm mostly asking for
a. A "canonical" generator/processor, if any exists
b. Tips on how you manage all this! Closest I've found is the github-tools, but that (on really quick glance) does not seem to cover generating the README's.

Thank you for your time and all the amazing work your doing!

[wooorm]

Thanks for your kind words, @tefkah!
Most questions/issues/etc are a bit entitled, or at least frustrated in the moment. Or just cold. So it’s really nice to see such messages! Makes my day.

On to How: well, it’s all pretty manual. I go through most projects like once every one or two years. Make sure things are consistent.
Recently, with types and ESM, that was a lot of the focus, a lot of breaking changes.
I’ve also been trying to get the docs better with the “what is this”, “when should I use this”, “security”, “types” sections, for the parsing project a “syntax”, for the AST projects a “syntax tree”, and for the high-level projects with lots of users an “examples” section.

It’s a bit tedious, that process. But it’s also nice. Some relaxed work. Especially after a giant, very challenging, project (https://github.com/wooorm/mdxjs-rs). It isn’t really about those particular projects, but as a whole, as you mention, I think this consistency and quality is what makes my work unique.

We do “dogfeed” our own tools. As in, remark-cli with a pretty strong preset (remark-preset-wooorm) is used. It also checks some natural language mistakes (such as duplicate words, as in the the). And it generates a ToC. And formats everything.

I have rather strong preferences on what tools to use. What styles to use. For things like TS through JSDoc instead of TS compiling to JS for example. I held on to ES3 for very long. And, of course, I have strong preferences on how markdown/natural language/readmes should be written.
That can be annoying for other folks. But I think the important part is: expect this thing to exist for 10+ years. Make sure it’s consistent. You don’t want to argue much about style choices. And you don’t want to rewrite everything every couple of years. Trust in JavaScript. Bet on standards.

Here’s a recent example of a very low-level, and personal, project: https://github.com/words/stemmer. 8 years old but still going strong! The tools and style there are what I am currently going with!

[matthias-ccri]

expect this thing to exist for 10+ years

Forget 10 years ... this thing will be running in 100 years!

[wooorm]

😅😬