documentation-framework VS bun

I forget the terminology, but there's a good "grid" breakdown of documentation types (I think this one: https://documentation.divio.com ) that I've simplified a bit for the internal documentation I'm involved with.

* README, HOWTO, INFO, PROJECT, DESIGN, NOTES, FAQ

When I pull down a `git` repo, I read the `README.md` (of course). I make my own `NOTES.md` (eg: `.gitignore`'d) of what commands, environment variables, useful blog posts, search results, whatever. Rarely do I share or encourage sharing of `NOTES.md` wholesale, but it's helpful to be able to pull out a few snippets or re-orient myself when coming back to that software/project.

Then, other documents get prefixed with "HOWTO-Do-Some-Specific-Thing.md", or "INFO-Some-Particular-Component.md".

"PROJECT-...", and "DESIGN-..." are "dangerous" ones in that they can quickly fall out of date, but they can be very useful while they're being actively managed. I guess personally I've started making sure to include dates or "eras" in the title, eg: "PROJECT-[2024-Feb]-Add-Foo-Support.md" or "DESIGN-[2024-02-14]-...". Stuff that's outlived its usefulness can probably be moved to an `ARCHIVE/...` in case you need it later, but keep it out of the way from confusing newcomers 1-3 years from now.

"FAQ-..." almost never comes into play (hopefully) b/c it should mostly get absorbed into "HOWTO-..." or product improvements, and few products seem to rise to the level of needing FREQUENTLY asked questions. Ideally FAQ's would "go away" with work on the product or other documentation, but I've had some success with it as like sales-oriented (and ideally: sales-managed) FAQ / Canned Customer Response learnings.

Putting it all together you get something like:

  * README.md

Resource: Documentation Best Practices - GitBook

I would not suggest people to follow this in 2024 if they are building any system of non-trivial scope and expect it to be adopted by others who are not required to adopt it.

Back in 2017, I compared "code as documentation" to being dropped into on the street of an unfamiliar city, while a good documentation can serve as a map of the city. [1]

Nearly all recent successful efforts for large new systems understand the value of both high-level overviews and detailed examples / onboarding materials to make adoption easier. When solutions to a certain problem are abundant, people do not need to settle for options that do not have great supporting documentation of the four primary kinds. [2]

[1] https://speakerdeck.com/maxvt/i-got-a-lot-of-problems-with-i...

[2] https://documentation.divio.com/

In the whole spectrum of documentation, man pages were designed to cater for a very specific need: information-oriented reference data. Check https://documentation.divio.com/ for a wonderful classification of documentation into four quadrants: reference, explanations, tutorials, and how-to guides. On the other hand, one can write info files for any of the use cases. That does not make info format inherently better or worse than man pages.

During the years, there have been many attempts to bridge the format gap, and convert texts from one representation to another. One of the most ambitious ones was in Tkman, a man viewer built on then Tcl/Tk system. Its really interesting part was the inclusion of rman, or RosettaMan, a converter of text to a somewhat abstract representation that could then be viewed via a GUI.

I personally look for well-crafted man pages as a sign of quality in software and try to provide them in everything I develop. I admit that I don't often find the time or motivation to write non-reference documentation (like tutorials).

I ran into the divio documentation guide recently that seems to have some awesome "how to write docs" docs

https://documentation.divio.com/ is a good overview of the "four types of documentation" paradigm: tutorials, how-to guides, explanations, and reference have to all exist.

One of my major gripes with the JS/TS ecosystem is that "explanations" are sorely lacking. See https://www.typescriptlang.org/tsconfig for the relevant documentation for tsconfig files. Tutorials are on the page, how-to guides abound on the wider internet (like the OP), and the linked TSConfig Reference and JSON Schema (used in code completion in IDEs) are together absolutely massive.

But an explanation is missing! There is no official documentation about how different options interact to say: as I'm walking a file tree as the Typescript compiler, this is how I will interpret a certain file I encounter, what will be outputted, and how that will be interpreted by bundlers and browsers, especially in an ESM world.

https://medium.com/extra-credit-by-guild/tsconfig-json-demys... is in the right direction, but outdated as ESM has become much more popular in the past 3 years, and still organized by option (so it's already somewhat in the "reference" world).

IMO even independent of documentation, the industry's move to ESM is problematic: https://gist.github.com/joepie91/bca2fda868c1e8b2c2caf76af7d... describes many of the issues. But they're certainly exacerbated by good explanation-style documentation that helps people understand how ESM works under the hood!

I really like the system detailed here: https://documentation.divio.com/. That's targeted more towards externally visible docs, but IMO adapts pretty well as for internal resources too.

It has a decent compatibility with both Jest and Vitest's APIs (you can track progress here so you can use it as almost a drop-in replacement for either. Just as Node's, it has describe/it, mock, test and others, but with the expect syntax (which I find more readable). For example:

In this third and final article in the series on HTML Streaming, we will explore the practical implementation of the Diff DOM Streaming library in web browsing. This approach will allow any website using web components to retain its state during browsing. We will discuss in detail how to achieve this step by step using VanillaJS and Bun.

At Node Conference 2023, Jarred Sumner (creator of Bun) showed a demo of server components in Bun, so there is at least partial support in that ecosystem. The Bun repo provides bun-plugin-server-components as the official plugin for server components. And while I haven’t looked at it in-depth, Marz claims to be a “React Server Components Framework for Bun”.

Continuously evolving, Bun is currently optimized for MacOS and Linux, with ongoing efforts towards Windows compatibility. Tailored for resource-constrained environments like serverless functions, it emerges as an ideal solution. The Bun team is committed to achieving comprehensive Node.js compatibility and seamless integration with prevalent frameworks. For those intrigued by Bun's potential and want to give it a try, more information is available on its website at https://bun.sh/.

Let’s say you are interested in learning more about Bun and probably give it a try. Bun has a website, where you can learn more about Bun and its features (including all the benchmark data captured in this issue), and here is the link.

Looks like it, it seems the 2% are mostly odd platform specific issues that the authors' did not deem very important (my assumption for the release happening anyway). AFAIK this[1] PR tries to fix them.

[1]: https://github.com/oven-sh/bun/pull/9729

Bun has a solution for it. First of all, it already has a list of trusted dependencies. For them, Bun will execute all necessary scripts by default. Otherwise, you can add it to trustedDependecies in your package.json file. In Bun community usage of trustedDependencies is a hot topic. There are several suggestions on how to improve it.

Install Node.js (or Bun, or Deno, or whatever JS runtime you prefer) if it's not there

I think maybe I was unclear. I'm talking about writing libraries that abstract across these differences and provide a single API, as sibling describes. I already know it's possible. I made a simple filesystem abstraction here[0] and a very simple HTTP library that uses it here[1]. They both work in Node/Deno and the browser. Unfortunately I ran into issues with Bun's slice implementation[2]. But I suspect there's a much better way of detecting and using the different backends.

[0]: https://github.com/waygate-io/fs-js

[1]: https://github.com/waygate-io/http-js

[2]: https://github.com/oven-sh/bun/issues/7057