Skip to content

Instantly share code, notes, and snippets.

@tmcw

tmcw/documentation-direction.md

Created July 27, 2017 19:24
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save tmcw/24562948dfbbe26ad1c4078b76aa044d to your computer and use it in GitHub Desktop.
Save tmcw/24562948dfbbe26ad1c4078b76aa044d to your computer and use it in GitHub Desktop.
Download ZIP
Raw
documentation-direction.md

documentation.js direction

I've been meditating on the direction of documentation.js going forward. Here's what I've decided on for now:

ground-up rebuild for modern javascript only

I'm going to rebuild documentation.js from the ground up, using a frontend that relies heavily on Flow annotations, and only supports export/import following. That means:

  • CommonJS import/export will no longer be supported
  • JSDoc types will no longer be supported

strict separation between input and output

Additionally, I'm going to build a new output stage, based on Gatsby, batfish, or another prior art.

These changes are bound to be controversial. This means cutting support for many projects that relied on documentation.js's semi-compatibility with JSDoc. But what it ends up being is:

  • Supporting full JSDoc in modern JavaScript is a wicked problem. The spec is incomplete, doesn't have parity with Flow or TypeScript, and isn't actively maintained. It's a constantly-blocking upstream with no clear future.
  • I could try to, say, adopt the entire JSDoc spec and try to build consensus. Unfortunately, the JavaScript documentation world basically doesn't do consensus. Plus, JSDoc just isn't fun and that's even more time than I have for documentation.js, and from what I've seen, the contributor base won't grow: few people contribute.
  • Similarly, supporting CommonJS module visibility is a wicked problem that's cleanly solved by ES6 import/exports.

So, to be clear:

  • If you really want to continue the tradition of documentation.js-the-jsdoc-competitor, please fork and maintain a fork! It's an open source project, so my personal move away from that goal doesn't mean the goal is dead: it means the onus is on you, yes, you. Open source is people, and you can be one of those people!
  • I really apologize if this catches you by surprise and your project will be pwned by the change. I can, though, say:
    • Thank to semver this will never break an existing project
    • Old versions will always be available
    • As before: open source is people, and I am just one of those people, and you can be one too!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment