AI Image Pipeline Documentation

Definition. The record of a pipeline's steps, their order, their parameters and the rationale for each choice, so that the pipeline can be understood, modified and reproduced by someone other than its author. Undocumented pipelines become unmaintainable, and their parameters become cargo cult.

How it works. Document the canonical step order and why it is that order. Record each parameter with its value and the reason, since a parameter without a reason will be changed arbitrarily. Note the model versions and their evaluation results. Keep the documentation next to the code, and update it in the same change.

Example. A pipeline's sharpening amount is set to 0.6 with no explanation. A new engineer raises it to 1.2 to make images look sharper, and halos appear across the catalogue. The documentation records that 0.6 was chosen because 1.2 produced visible halos on text, and the change is reverted. The parameter's rationale prevents a repeat of an already-solved problem.

Use case. Documentation is required for any pipeline that will outlive its author, which is all of them. It is also the artefact that makes onboarding and safe modification possible.

Warnings. A parameter without a recorded reason will be changed arbitrarily. Never document only the steps without the rationale. And never let documentation live far from the code, since it will not be updated.

Limitations. Documentation takes time and is often skipped under delivery pressure. It also goes stale, so it must be updated in the same change as the code.

← Browse all glossary terms