Skip to content

Current maintenance status

Tom MacWright edited this page Oct 21, 2018 · 1 revision

Hello! This is Tom - I originally wrote documentation.js and am still the top contributor and main person who merges PRs, though there are now quite a few members and owners of the organization. I want to set expectations around the project. Here it goes:

Mostly documentation.js moves by PRs.

If you need a feature or a bugfix, the most efficient and often the only way that it will happen is that you'll do it yourself. That means you'll implement the fix or feature, test it, and contribute it back via a PR. I'm happy to review and merge the vast majority of PRs. I'll only reject pull requests when the code quality is very low, if they introduce new bugs, or if the PR departs significantly from the ideology of the project.

This means that, no, opening an issue won't lead directly to a fix. I don't spend hours of my own time working on this project anymore, and I don't feel a strong sense of responsibility if you tell me that you lost hours of your workday debugging some problem caused by documentation.js. I feel bad about those things, and feel sympathy for you as a person, but when it comes down to it, this is an open source project that is used by a community and is now maintained by a community. I pushed it 90% of the way, and if it's going the final 10%, you'll need to help.

My efforts are mostly directed toward my work/life balance (gardening, reading, and exploring San Francisco), work (Observable), and projects that still inspire me. I'm no longer super jazzed about the documentation.js approach, and I've started experiments about the future of documentation that go a different way and would serve a different audience. Particularly when it comes to JSDoc and Babel, these are technologies I no longer want to build with, for reasons that I've detailed in the past.

You might look at the list of open bugs and think that project health is low. That's fine, and kind of accurate. Open source in the sense of 'everyone giving back and helping out' never really panned out. It's probably crossing a line to call people who only open issues and never contribute changes 'selfish', but it's also inaccurate to see them as faultless in the current ecosystem. It's also unfortunate that the project has major corporate users who also haven't contributed fixes or features. If I were to do it again, I'd aim for a smaller problem set, tack on a restrictive license, or set clearer roles - and in fact I do plan on doing it again and I'll probably do those things.

I hope this doesn't dissuade anyone from contributing. It could really encourage people to contribute: if you believe in functional communities, here's the time and place to be the change.

Clone this wiki locally