search

alphagov / govuk-prototype-kit

Rapidly create HTML prototypes of GOV.UK services
https://prototype-kit.service.gov.uk
MIT License
306 stars 236 forks source link

We have no developer API documentation #1805

Closed lfdebrux closed 1 year ago

lfdebrux commented 1 year ago

Cause

We have a slowly growing programming interface for the prototype kit. This is documented from a user perspective at https://prototype-kit.service.gov.uk, but we don't have anything in the way of more traditional API documentation collecting together all the different methods and configuration options.

Consequence

For developers of the kit it's hard to know what we do and don't support already when planning implementation of new features. For people trying to write code that integrates with the kit (such as plugin developers) it is hard to know what they can do with the kit.

Impact of debt

Medium

Cost to pay down

High

joelanman commented 1 year ago

this would also make it easier to onboard the new devs

lfdebrux commented 1 year ago

Things that I would consider being in scope for this: anything exported by govuk-prototype-kit including routes API, filters API, etc. The JSON format we expect for plugins in govuk-prototype-kit-config.json, also which options we allow in app/config.json. Maybe also the blocks we have in layouts?

Some things to consider using for this include automated doc generation from JSDoc, JSON schema for configuration files for automated checking tools, that sort of thing. Keeping docs up-to-date is a difficult job.

lfdebrux commented 1 year ago

Some existing (but out of date) developer docs: https://docs.google.com/document/d/1DMu3MVB4iz3QI_xi93Ynw6-esLts-t-o9dY5zpevwLs/edit#heading=h.g0dcse92dyh7

lfdebrux commented 1 year ago

We're improving the situation somewhat in PR #1877, not sure if I feel this is entirely done yet though. I think it would be nice to have a wider coverage of JSDoc comments. However, that is probably a long-term goal.