3. What is twilio?
twilio makes it easy for developers to
integrate voice calling and messaging
into web and native mobile applications
4.
5. “The goal is to have lots of user-created
modules, that are all single-purpose and
focused...so you can iterate get the best
experience possible...”
12. HOW WE CAN HELP
• Provide accurate documentation optimized for how people read on
the internet (scanning and searching)
• Design idiomatic APIs that optimize for the job your module will be
hired to do
• Implement test automation and basic release management
14. DOCUMENT ALL THE THINGS
• Very few userland modules have effective docs - common open
source problem
• Every module has different documentation needs
• Great resource: Kevin Burke’s talk on this subject
• Two most important components for node modules:
• README (quick start)
• API Docs
15. AN EFFECTIVE README
• Focus on the job your module will be “hired” to do
• Get user to success ASAP by staying focused:
• What job does your module do?
• How do you install/configure it?
• ~3 examples of how to do the thing your module would be
hired to do
• Link to API docs and deeper info sources
17. EFFECTIVE API DOCS
• Describe the complete surface area of the API
• Provide context for how the API is meant to be used
• Make content readable and scannable
• Provide complete and correct examples, but do not rely on them as
API documentation
• “Read the tests” is a cop out (see above)
18. DESCRIBING A NODE.JS API
• Document all properties and functions from module.exports (harder
than it sounds)
• Document all function signatures
• Function docs should ideally have:
• Return value/type
• Argument types
• Example usage
19. PROVIDING CONTEXT
• Show how your code is intended to be used
• Demonstrate how it interconnects with other modules/platform
features
• Describe high-level use cases and concepts unique to your module
20. MAKE CONTENT READABLE
• Users don’t read docs word for word - they scan in an F shape,
looking for relevant bits
• Include a table of contents for longer content (https://github.com/
thlorenz/doctoc)
• Make the first 3-5 words of every line contain the most information
possible
• Use headers/images/code to break up scary blocks of text
• Limit text on a page to columns of ~80 characters
21. PROVIDE EXAMPLES
• Reinforce written docs with sample code that shows actual usage
• Ideally, examples should be copy/cut/paste ready - include any
necessary setup/teardown, including the “require”
• Accuracy is key - broken examples are super frustrating
24. NODE.JS MODULE API DESIGN
• Check out: https://www.youtube.com/watch?v=aAb7hSCtvGw
• Design for async usage
• Use streams for I/O
• Be mindful of the job your module has been hired to do
25. DESIGNING FOR ASYNC
• Do not release Zalgo
• Node core modules use a specific type of signature for async APIs
that require callbacks
• Function takes whatever arguments, and a callback
• Callback is called with any error received as the first argument,
formatted data is the second.
• Sometimes there’s a third arg with a “raw” value in userland
26. DESIGN FOR STREAMS
• If you do any sort of I/O, you’d do well to make your interface speak
streams
• Your API will interoperate well with the rest of the node ecosystem if
you work with readable and writable streams
• “When you grok streams, you grok node” - Isaac paraphrase
27. BE MINDFUL OF YOUR PURPOSE
• Your module might do a few different things, but it probably has a
few 80% use cases
• Your API should be designed to do those jobs as quickly and
efficiently as possible, with sensible default behavior
30. MANAGING YOUR PROJECT
• Ensure quality with testing and test automation (which can be super
easy)
• Ensure sanity with your module releases by using semantic
versioning
31. MANAGING YOUR PROJECT
• Promote quality with testing and test automation (which can be
super easy)
• Ensure sanity with your module releases by using semantic
versioning
32. TESTING/AUTOMATION
• Lots of great test frameworks, pick your favorite or just use assert
• Do support “npm test”
• Travis CI is your friend, and super easy to set up
33. RELEASE MANAGEMENT
• If you follow semantic versioning, you’re probably doing fine
• If an API breaks from 1.4 to 1.5, that’s a Very Bad Thing
• Use git tags that match your npm versions
• Doing the above makes release notes/change log very easy
35. WRAPPING UP
• You probably don’t get paid to write and share your module - thank
you for contributing!
• node.js relies on userland modules more than any other major
server-side platform
• If we care about the node ecosystem and community, we all have to
step up with the quality of our contributions