document intended modification pattern