How to write Documentation in QA
If you want do write good QA Documents you need to know such tips:
- use simple sentences;
- write any info like algorithm (step by step);
- use correct name of elements;
- don’t use words or phrases that have several meanings;
- use technical words and phrases;
- do not use abusive language.
- use templates.
In general, it’s good to keep these basic guidelines in mind:
➡️ One bug = one issue. Don’t include multiple bugs in same issue.
➡️ Avoid duplicates. Always try to search your current issue tracker for existing reports.
➡️ Reproduce the bug before creating the report. This makes it more likely that the developer will be able to reproduce the problem and identify where it comes from.
➡️ Don’t forget to KISS: keep it simple, stupid. Keep everything clear and focused on the problem, solution or idea at hand Using bullet points or numbered lists can help.
➡️ Use a professional bug tracker. This will help you keep everything in one place and avoid losing files and bug reports.
➡️ Be kind. Developers are people too and bugs happen – they’re part of the process in making great end products and websites.
1. Title
Keep it short and specific. Make sure it clearly summarizes what the bug is and mentions the location or category. Having a clear name or ID on your report makes it easier for the developer to find later on and merge any duplicates.
❌ Bad: «I can’t see the product when I add it, for some reason I try and it doesn’t. WHY? Fix it asap.»
This example is bad because it’s: vague, aggressive, includes too many words and asks for a solution to be implemented.
This is a better example:
✅ Good: “CART – New items added to cart do not appear”
This example is much better as it helps the developers instantly locate the issue (CART) and it focuses on the actual technical problem. When developers review it, they’ll be able to instantly assess the issue and decide to explore it by looking at the other elements of the bug report.
Here’s another set of bad and good example highlighting the points made above.
❌ Bad: «The text on the pricing page looks weird»
✅ Good: «PRICING – Headline text font size is incorrect»
2. Expected vs. actual results
Now take the time to explain to your developer what you expected to happen (sometimes this is referred to as the user story) and what actually happened.
Example:
Expected result: Item should be added to the cart when I click ‘add’
Actual result: Item does not appear in the cart
3. Steps to reproduce
Here is your opportunity to share the steps needed to recreate the bug. Assume that your developer has no idea about the bug you found – how does he reproduce it?
The steps to follow should be comprehensive, easy to understand and short. The most important goal of this step is for your developer to experience the bug first-hand.
Example:
Step 1: Search for product XYZ
Step 2: Click on product XYZ in search results
Step 3: Click on ‘add to cart’ button
Step 4: Go to cart
Pro tip:
Use a numbered list to explain the steps
If you’ve already managed to recreate the issue several times, you can include the reproducibility rate (example: 12/12 times bug reproduced).
4. Environment
Websites and apps can behave very differently depending on the environment used. It’s critical that the following information be included in any report your share:
- Browser
- Operating Systems (OS) and version
- Screen size
- Zoom level
- Pixel ratio
5. Visual proof
We all know that a picture is worth a thousand words, well, that can also be true in bug reporting. While it may not tell the whole story, a screenshot or video can add a lot of value by getting your developers to see and understand the problem faster.
