This is definitely the best approach in my opinion, providing the people writing the docs are capable of contributing directly. One of my projects[0] builds an

This is definitely the best approach in my opinion, providing the people writing the docs are capable of contributing directly. One of my projects[0] builds and deploys a static documentation site[1] on every push to master. The static site generator (Nanoc, in this case) imports the library and uses it to publish its own documentation. All the examples are snippets of code[2] that are both displayed as-is and eval'd into the final output. The guide can never be out of sync with the library. [0] https://github.com/dfe-digital/govuk_design_system_formbuilder/ https://github.com/dfe-digital/govuk_design_system_formbuild... [1] https://govuk-form-builder.netlify.app/ https://govuk-form-builder.netlify.app/ [2] https://github.com/DFE-Digital/govuk_design_system_formbuilder/blob/master/guide/lib/examples/text_input.rb https://github.com/DFE-Digital/govuk_design_system_formbuild...