Secret ingredients to quality software


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

Last updated by Tiago Araújo [SSW] on 15 Jun 2021 04:28 pm (2 days 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?)

From X...

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

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

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

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

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".

A pull request is a request to make changes to 1 or more files. GitHub provides out of the box functionality for reviewing changes in a pull request. This process is as follows

  1. Open the pull request
  2. Examine the changes using the tabs

    • Conversations: see comments people have made about the change
    • Commits: see comments associated with the changes the requester has made
    • Checks: You can ignore this if you are not a developer
    • Files changed * Important *: see the difference between the old and new files being changed. Red highlighting indicates deleted parts and green highlighting indicates added parts.

    Figure: Review 3 of the 4 tabs in a GitHub pull request

    Figure: The best view is via the "Display the rich diff" button. This visual preview of the changes to a markdown file is accessed via Files changed | Display the rich diff

  3. Next is to approve or ask for changes.

    1. Files changed | Review changes

    2. Add a comment with your feedback.

    3. Choose "Approve" to mark it as ready to go live.

    If it is not ready, then choose "Comment" for general feedback or "Request changes" for mandatory changes.

    4. Press "Submit review" so that the requester can see it.

    Submitting a pull request review

  4. Congratulations! Your review has been submitted ⭐
Adam CoganAdam Cogan
Cameron ShawCameron Shaw
Tiago AraujoTiago Araujo
Piers SinclairPiers Sinclair

We open source. This page is on GitHub