Secret ingredients to quality software

SSW Foursquare

Do you ask for content changes using from X to Y?

Last updated by Tiago Araújo [SSW] on 11 May 2022 02:07 am (3 months ago) See History

When asking for changes to be made to any file like a web page, Word document, PowerPoint slide or code, always include the original version of the content ("X") together with the changes you require ("Y"). This means you have at hand a history of the page or file as it currently stands allowing for convenient future reference and also makes it very clear to the person doing the changes exactly what the new file is meant to look like.

Make the changes even easier to see and understand by highlighting in red what you want to delete (only do this on the "From" section) and in yellow what you want to be added/updated (only do this on the "To" section). All text we do not write ourselves should be indented, so this includes paragraphs we are copying and pasting (see Do you use indentation for readability?)

Figure: Bad example - original version of content has not been included in the email

Figure: Good Example - it has 'From' and 'To' with changes highlighted... so it is clear what needs to be changed

Video: Top 10+ Rules to Better Email Communication with Ulysses Maclaren

Alternative - What if there are too many changes?

Sometimes you have a lot of content and too many changes, making the process "from X to Y" too arduous. In this case is recommended to use Word 'Track Changes' functionality.

word track changes
Figure: A Word document with 'Track Changes' ON is recommended if you have too many changes

Alternative - What if you have a website managed by GitHub?

Some websites use GitHub to manage their files (e.g. SSW Rules). GitHub makes reviewing changes easy through "Pull Requests".

Figure: This visual preview of the changes to a Markdown file in GitHub

Adam CoganAdam Cogan
Cameron ShawCameron Shaw
Tiago AraujoTiago Araujo
Piers SinclairPiers Sinclair

We open source. Powered by GitHub