When you are using a library seriously, you will spend a lot of time with its documentation. It's one of those things that sets good libraries apart from the rest. Even a fantastic idea can go overlooked if it's too difficult to get into and understand.
Writing good documentation isn't easy. Tom MacWright has developed documentation.js to help exactly with this.
Mapbox. I wrote lots of libraries that sliced and diced geospatial data, showed it on screens, and helped people design maps.At work, I'm a software engineer but also spend a lot of time writing, designing products, and so on. Until recently, that was in the mapping space at
The last big project I worked on there was Mapbox Studio. There are enough hard problems in the world of maps to spend a lifetime trying to solve them, but I decided to try out some new domains. I've been taking a few months off to relax, so recently I've been spending more time training a few bonsai trees and maintaining open source projects.
documentation.js is a program that generates documentation from the source code of other programs. The documentation is a combination of things that you write, like paragraphs, explaining what a function does, and things that documentation.js itself can infer, like the types of parameters and return values.
Then there's the trickiest step: combining that automatically-derived documentation with explicit documentation, things that people write themselves as source code comments. That's all done by merging tree data-structures and so on, and is one of the parts I most want to refactor!
Then, finally, it has a significant output system that can generate JSON, Markdown, and HTML documentation. I want the output to be great as a carrot for people to write documentation, so the project itself is responsible for at least the official theme.
Documentation is a crowded space! There are lots of documentation generators out there, which is why I maintain a big list of them on a wiki page called See Also.
The biggest player out there is JSDoc, so I'll describe how documentation.js is different than it. First off, documentation.js has a system for automatically figuring out which files to document - doing the same trick as webpack or browserify to figure out what requires what and which functions are exported. I wanted that, so that code itself would be the authority that tells us what is a public interface and what is private.
Plus, it's a lot of fun. Documentation generation might seem bland at first glance, but it's an adventure through parsing, generation, static analysis, and so much more.
My highest priority is to grow the documentation.js community. I have lots of strategies for doing this, but nothing has worked so far. That's the most important thing to me, and I also think to most maintainers of large projects.
It's bright but uncertain: I love where the project is currently, but it's substantial and has many areas that could use their owners. In a perfect world we'd have a team of 4 or 5 and, for an example of the ownership, support for TypeScript could be "owned" by someone who needed and used that support on a daily basis. As it stands right now, I'm pumped when another project or company adopts the module, but the ratio of work to contributors continues to increase.
Web development is weird and crazy right now. I think the biggest, most exciting development we'll see in the next year is the effect of the bleeding-edge tech that was introduced two years ago becoming standard in all browsers. Native support for ES6 modules, for instance, will change the landscape.
First of all, stay patient. Coding is challenging and frustrating, and the single most reliable sign I've noticed of whether people will succeed is their ability to cope with frustration. You might need to laugh at yourself, or stop and breathe, or take a walk. But find something that works, because the feeling of being fooled by a program that should work will never end.
Secondly, you can get far by only working on the surface level, but you really shouldn't. Dig in, learn what's under the hood, read the code, and you'll get better, faster.
Thanks for having me! Stay chill, and remember: the open source community is just some people, and it could be you too. Only you can fight maintainer burnout by being friendly and contributing code, documentation, or even just love to your favorite projects.
Thanks for the interview Tom! I hope people find your tool and we get enhanced documentation as a result.
See documentation.js site and documentation.js GitHub page to learn more about the project.