Re:Making world-class docs takes effort
by yourapostasy on Monday September 06, 2021 @10:41PM
(#28440295)
> For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.
I fantasize about an environment where a GUI's internals and interfaces are annotated sufficiently to discretely call from unit and integration tests, and version-controlled instances of those are linked to non-technical task management, user documentation, support tickets, support knowledge bases, patch configuration management, and so on. In this fantasy, if code changes a GUI element enough to alter its appearance or fail a unit test of the GUI, it automatically triggers a re-imaging of snapshots for it in all downstream linked documentation references and issues PR's for human intervention reviews of the new images (with adjustable cropping for finalized approvals).
That's my holy grail of single-source documentation.
I fantasize about an environment where a GUI's internals and interfaces are annotated sufficiently to discretely call from unit and integration tests, and version-controlled instances of those are linked to non-technical task management, user documentation, support tickets, support knowledge bases, patch configuration management, and so on. In this fantasy, if code changes a GUI element enough to alter its appearance or fail a unit test of the GUI, it automatically triggers a re-imaging of snapshots for it in all downstream linked documentation references and issues PR's for human intervention reviews of the new images (with adjustable cropping for finalized approvals).
That's my holy grail of single-source documentation.