Automate API documentation

[caw310]

Problem Statement

Many configuration options are not documented, which makes it difficult for VFS teams to build forms quickly and easily.

How might we make it easier for VFS teams to identify the correct configuration to implement the correct component for their features/products.

Hypothesis or Bet

If we have more robust documentation which includes all configuration option of components, VSP will be giving less support to VFS teams.

If we have more robust documentation, VFS teams will be able to identify the correct components to use right away.

We will know we're done when... ("Definition of Done")

What requirements does this project need to meet for you to finish this initiative?

• [ ] Serve the forms library API documentation as HTML on a publicly accessible site
• [ ] Automatically update the hosted documentation from the master branch

Launch Checklist

Is this service / tool / feature...

Tool

... tested?

• [ ] Usability test (TODO: link) has been performed, to validate that new changes enable users to do what was intended and that these changes don't worsen quality elsewhere. If usability test isn't relevant for this change, document the reason for skipping it.
  • [ ] ... and issues discovered in usability testing have been addressed.
  • Note on skipping: metrics that show the impact of before/after can be a substitute for usability testing.
• [ ] End-to-end manual QA or UAT is complete, to validate there are no high-severity issues before launching
• [ ] (if applicable) New functionality has thorough, automated tests running in CI/CD

... documented?

• [ ] New documentation is written pursuant to our documentation style guide
• [ ] Product is included in the List of VSP Products
  • List the existing product that this initiative fits within, or add a new product to this list.
• [ ] Internal-facing: there's a Product Outline checked into products/platform/PRODUCT_NAME/
  • Note: the Product Directory Name should match 1:1 with the List of VSP Products
• [ ] External-facing: a VFS-facing README exists for this product/feature tool
  • [ ] ... and should be located at platform/PRODUCT_NAME/README.md
• [ ] External-facing: a User Guide exists for this product/feature/tool, and is updated for changes from this initiative
  • [ ] ... and should be linked from the VFS-facing README for your product
  • [ ] ... and should be located within platform/PRODUCT_NAME/, unless you already have another location for it
  • [ ] (if applicable)... and post to #vsp-content-ia about whether this should be added to the Documentation homepage
• [ ] (if applicable) Post to #vsp-service-design for external communication about this change (e.g. VSP Newsletter, customer-facing meetings)

... measurable

• [ ] (if applicable) This change has clearly-defined success metrics, with instrumentation of those analytics where possible, or a reason documented for skipping it.
  • For help, see: Analytics team
• [ ] This change has an accompanying VSP Initiative Release Plan.

Required Artifacts

Documentation

• PRODUCT_NAME: directory name used for your product documentation
• Product Outline: https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/teams/vsp/teams/design-system/automate-API-docs.md
• README: link to VFS-facing README for your product
• User Guide: link to User Guide

Testing

• Usability test: link to GitHub issue, or provide reason for skipping
• Manual QA: link to GitHub issue or documented results
• Automated tests: link to tests, or "N/A"

Measurement

• Success metrics: link to where success metrics are measured, or where they're defined (Product Outline is OK), or provide reason for skipping
• Release plan: link to Release Plan ticket

[caw310]

Closing