Your Documentation and Engineering teams
But there's a lot about process problems to address too. Please come find me afterwards and let's talk! 👍
👉 and we're now adopting them to develop our public developer documentation at InVision!
Fortunately, there are team processes and automation patterns out there that can help you stop the upstream/downstream nightmare entirely.
1. Write documentation markup in your App's method definitions that allow you to define custom tags you can parse with an AST:
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.
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
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! 👍
Thank you! 🙏