Seamlessly Integrating

Howdy!

I'm @obensource.

I build tech communities

(InVisionApp, Node.js, tc39, W3C)

♡ the Internet of Music.

Tools that reduce complexity are AWESOME!

This talk is about Engineering Solutions.

But there's a lot about process problems to address too. Please come find me afterwards and let's talk! 👍

Building sustainable API docs is hard.

The following automation patterns have been developed, used, and inspired by the Electron and Node.js teams!

👉 and we're now adopting them to develop our public developer documentation at InVision!

Upstream

(API Team)

Midstream

(Documentation Team)

Downstream

(End Users)

Documentation sets the tone for your product's Developer Experience.

 Fortunately, there are team processes and automation patterns out there that can help you stop the upstream/downstream nightmare entirely.

Three powerful concepts:

Generate 'Skeleton Docs' from your source repository

Make your documentation repository the

'single source of truth' for all the docs.

Treat your Documentation's repo as a text-source repository that can be exported as a Node module

Technical Overview

1. Write documentation markup in your App's method definitions that allow you to define custom tags you can parse with an AST:

https://github.com/Microsoft/tsdoc

2. As a step in your App's release cycle:
 

Run your documentation markup parsing tool to produce its equivalent in JSON, and export timestamped .json files to a local 'dump' folder.

Example: your-app/src/doc-dist

3. Run a scheduled task once a day that clones your App’s repo, and checks for files that we’re made in the past 24 hours.

Example: Heroku schedule task

https://devcenter.heroku.com/articles/scheduler

• Clone the App and Documentation repos.
• Convert your documentation's 'source' format (example: markdown) into .json.
• Diff the existing docs with the new changes.
• Update or add the incoming values.
• Export the new JSON so your documentation-site team can easily import the always up-to-date docs.
• Convert the updated JSON back into markdown, and submit a PR to run your tests and integrate the new changes.

Next Steps (if new files exist):

4. Publish your documentation repo as an npm module, so you can import one giant JSON object containing all your docs to any end destination site you wish. 😎

Bonus: This process makes setting up Internationalization super easy!

Do you have UI examples you have to maintain too?
 

🎷 No problem! 🎷
 

Don’t use screenshots, they're not maintainable.

Consider using a tool like storybook, and let your scheduled documentation task runner submit code PRs that mirror the samples you define in your reference documentation!

Now your users can actually interact with your UI samples, and you don’t have to maintain screenshots! 👍

Lastly:

I hope this helps.

Thank you! 🙏