Add UI testing tips to docs (wordpress-mobile#20576)

* Move UI testing checklist to existing docs The proposal moves the newly added UI testing checklist to the existing `docs` folder and turns them into testing considerations. These considerations are roughly split between various existing docs: accessibility, localization, pull requests, RTL language support. * Added link to PR guideline from PR template * Revert changes to PR template --------- Co-authored-by: Paul Von Schrottky <[email protected]>
jeff4a501 · May 3, 2023 · 88e8e7c · 88e8e7c
1 parent 19f77f3
commit 88e8e7c
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 12 deletions.
diff --git a/docs/accessibility-guidelines.md b/docs/accessibility-guidelines.md
@@ -8,6 +8,12 @@ This is a short recap of the most important points for a successful implementati
 We also have a fast guide on [how to use VoiceOver](using-voiceover.md)
 
 ## Dynamic type
+
+### Testing considerations
+
+Verify how UI changes look with the system font set to larger and smaller sizes. Also try system-wide bold text.
+
+### Coding considerations
 -   Avoid constraining the height of a  `UILabel`,  `UIButton`, or any view that has a  `UILabel`  or a  `UIButton`  as a child view.
 -   In cases where a minimum height is necessary, use a constraint relation`greaterThanOrEqualTo`.
 -   In most cases for  `UIButton`  instances, setting  `.contentEdgeInsets`  top and bottom will be enough to get a minimum height.
@@ -25,8 +31,16 @@ We also have a fast guide on [how to use VoiceOver](using-voiceover.md)
 
 Be careful with [static tables.](dynamic-type-guidelines.md#the-static-tableview-case)
 
+## Increased contrast
+
+Verify how UI changes look with the system-wide high contrast.
+
 ## VoiceOver
 
 - To test the new (or modified) UI with VoiceOver is the best we can do to ensure a good adoption of this feature.
 - Add accessibility labels to elements with not enough text-based information (i.e a button with just a number or an image).
-- For complex UI elements that represent one unit of information, make that unit a single VoiceOver element with a label that explains its content as we would explain it to another person.
+- For complex UI elements that represent one unit of information, make that unit a single VoiceOver element with a label that explains its content as we would explain it to another person.
+
+## Dark mode
+
+Verify how UI changes look in light and dark modes.
diff --git a/docs/localization.md b/docs/localization.md
@@ -1,10 +1,12 @@
 # Localization
 
+## Technical consideraations
+
 During development, using [`NSLocalizedString()`](https://developer.apple.com/documentation/foundation/nslocalizedstring) in the code should be enough. You shouldn't need to touch the `Localizable.strings` files manually.
 
 During the release process, `NSLocalizedString` statements are scanned and stored in the `Localizable.strings` file. The file is then uploaded to [GlotPress](https://translate.wordpress.org/projects/apps/ios/) for translation. Before the release build is finalized, all the translations are grabbed from GlotPress and saved back to the `Localizable.strings` files.
 
-## Use unique reverse-DNS naming style Keys
+### Use unique reverse-DNS naming style Keys
 
 Use unique reverse-DNS naming style for keys of localized strings (instead of using the English copy as key). This allows to avoid issues where the same word in English could need different translations based on context, or very long keys causing issues with some translation services.
 
@@ -20,7 +22,7 @@ let postBtnTitle = NSLocalizedString("Post", comment: "Verb. Action to publish a
 let postType = NSLocalizedString("Post", comment: "Noun. Describes when an entry is a blog post (and not story or page)"
 ```
 
-## Always add Comments
+### Always add Comments
 
 Always add a meaningful comment. If possible, describe where and how the string will be used. If there are placeholders, describe what each placeholder is. 
 
@@ -44,7 +46,7 @@ let succeededMessage = String(format: NSLocalizedString(
 
 Comments help give more context to translators.
 
-## Use positional placeholders
+### Use positional placeholders
 
 Use the `%n$x` format (with `n` being an integer for the parameter position/index in the arguments to `String(format:)`, and `x` being one of the type specifiers like `@` or `d`); in particular, don't use just `%x` (the one without explicit positional index) for positional placeholders. This way, translators will not risk of messing up the parameter resolution order when translating the copy in locales where the order of the words in the sentence might be different than the one in English.
 
@@ -66,7 +68,7 @@ let alertWarning = String(format: NSLocalizedString(
 ), accountName, locationName)
 ```
 
-## Do not use Variables
+### Do not use Variables
 
 Do not use variables as the argument of `NSLocalizedString()` (neither for the key, the value or the comment). The string key, value and comment will not be automatically picked up by the `genstrings` tool which expects string literals.
 
@@ -86,7 +88,7 @@ let comment = "Put a meaningful comment here."
 myTextLabel?.text = NSLocalizedString("some.place.title", value: "This is the text I want to translate.", comment: comment)
 ```
 
-## Do not use Interpolated Strings
+### Do not use Interpolated Strings
 
 Interpolated strings are harder to understand by translators and they may end up translating/changing the variable name, causing a crash.
 
@@ -105,7 +107,7 @@ let year = 2019
 let str = NSLocalizedString("mysite.copyrightNotice.title", value: "© \(year) Acme, Inc.", comment: "Copyright Notice")
 ```
 
-## Multiline Strings
+### Multiline Strings
 
 For readability, you can split the string and concatenate the parts using the plus (`+`) symbol. 
 
@@ -132,7 +134,7 @@ NSLocalizedString(
 )
 ```
 
-## Pluralization
+### Pluralization
 
 GlotPress currently does not support pluralization using the [`.stringsdict` file](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html#//apple_ref/doc/uid/10000171i-CH5-SW10). So, right now, you have to support plurals manually by having separate localized strings.
 
@@ -148,10 +150,14 @@ struct PostCountLabels {
 let postCountText = (count == 1 ? PostCountLabels.singular : PostCountLabels.plural)
 ```
 
-## Numbers
+### Numbers
 
 Localize numbers whenever possible. 
 
 ```swift
 let localizedCount = NumberFormatter.localizedString(from: NSNumber(value: count), number: .none)
-```
+```
+
+## Testing considerations
+
+Test changes that include localized content by using large words or with letters/accents not frequently used in English.
diff --git a/docs/pull-request-guidelines.md b/docs/pull-request-guidelines.md
@@ -18,7 +18,7 @@ When you are ready, please, spend time crafting a good Pull Request, since it wi
 
 **Description**: Take the time to write a good summary. Why is it needed? What does it do? When fixing bugs try to avoid just writing “See original issue” – clarify what the problem was and how you’ve fixed it.
 
-**Testing instructions**: Step by step testing instructions. When necessary break out individual scenarios that need testing, consider including a checklist for the reviewer to go through.
+**Testing instructions**: Step by step testing instructions. When necessary break out individual scenarios that need testing, consider including a checklist for the reviewer to go through. Consider whether the change warrants accessibility testing. For UI changes, consider testing on different form factors (iPad, iPhone, iPad split screen) and in landscape and portrait orientations. 
 
 **Images and Gif**: Include before and after images or gifs when appropriate.
 

diff --git a/docs/right-to-left-layout-support-guidelines.md b/docs/right-to-left-layout-support-guidelines.md
@@ -2,6 +2,8 @@
 
 Supporting right to left layout is fairly simple and most of the hard work has already been done by Apple.
 
+## Technical considerations
+
 Here are a few tips to ensure this implementation is flawless throughout the app: 
 
 * Avoid using `.textAlignment = .left/.right` in favor of `.natural`
@@ -31,4 +33,8 @@ The problem arises when we want to customize the rect size for those accessory v
 The easiest way to counter this problem is by not overriding those methods, and instead, adding the required insets to the accessory view itself.
 
 If the requested layout is more complex, take  this problem into account and test the RTL layout until it works :]
-You can get ideas by looking at the `WPWalkthroughTextField` class.
+You can get ideas by looking at the `WPWalkthroughTextField` class.
+
+## Testing considerations
+
+UI changes related to copy should be tested with right-to-left languages. Even if translation isn’t complete, formatting should still respect the right-to-left layout.