Training and Verifying

Defect Management

What do you need for Training Materials?

If you've been following along with these blogs from the beginning, you have a good high level understanding of what Defect Management is (from Blog #1), and how to set up your defect repository (from Blog #2). Now, we have everything set up and ready to go… except no one knows how to use this cool new tool you've set up to capture the defects.

So - Training!

But, as usual, there are many flavors of audiences, documentation and training, and you need to take all of these into account.


    Documentation Types

    We can separate the types of documentation you will need to create into two types: Informational and Educational. The first type, Informational, would usually be a Word-type document (sorry for the Microsoft-centric verbiage) where you can spend your time detailing everything out, step by step, along with LOTS of pictures and diagrams. These are the documents that will be in the archive for anyone to be able to retrieve and review in order to learn how to work with the application, or with the processes being outlined. The idea of these is that they are COMPLETE. If a user needs to know about something, all of the information is detailed in one of these documents, and once they finish reading and digesting it, they should know everything they need to know to accomplish their tasks. These might include (but are certainly not limited to):

    • Admin work - adding users, unlocking them, changing their passwords, etc.
    • How to enter a defect into the system
    • How to write up a defect well
    • How to execute a test case
    • What the overall Defect Management process is, why we need it
    • What Triage Meetings are, and how they are run, who should be there, etc.
    • How to import Requirements or Test Cases or Defects into the repository tool
    • How to export data for metrics
    • Etc., etc…

    This list goes on and on, depending on the features of your repository tool, the Defect Management process you have in place, what people are asking for, and, of course, the time available to write it all up.

    Whereas the first type, Informational, could be likened to a text book for a college course, the second type, Educational, would be likened to the classroom lecture itself. A higher level, visual run-through of the topic, giving the most critical and needed information, but not necessarily diving deep into all of the areas. It would be supported by the Informational documentation if people need that deep-dive for specifics, but at the end of the "class", the user should be able to understand and apply what they have learned in order to get their job done, but not necessarily all of the bits and pieces, the details, the hidden features of the product.

    These come in two flavors: Videos and the PowerPoint slide type of classroom presentations. The presentation decks are what you would put together if you planned, for instance, on standing in front of a classroom (virtual or in person) of testers eager to learn how to start logging defects. You would generally create a deck of slides at a fairly high level, and then speak to your audience about each one, going into details verbally. The decks themselves would not be a very useful tool on their own if a user took a look at it alone, unless the notes for each slide were expansive. HOWEVER, a recording of the classroom session would be worth archiving. Make a point of recording all of your presentations. You can keep or discard them later, but as a first cut, others who were not able to make the class have something to work with.

    Now, VIDEOS have a place all of their own, and are very important. The problem with a recording of a class is that they are frequently interrupted with questions (not bad, but an interruption none the less), or with audio issues, or just the fact that they are live and not controlled. A video recording of your screen and voice of you going over everything covered in the class, including addressing any questions that were raised, is a much smoother presentation of the same information, more controlled, step-by-step the way you want it presented. It can be laid out in advance, practiced, started and stopped, and even discarded and restarted if needed. In addition, you can show yourself working in the actual application itself rather than slides of pictures. BOTH have their place, both have their strengths, so consider them both as possible additions to your library of documentation.


    By audiences here, I don't mean the people sitting in the conference room watching you perform. Rather, I mean the TARGET audience(s) you are looking to educate on the ins and outs of Defect Management or the use of the repository tool (or other specifics):

    • Admins
    • Testers and Developers
    • Project Managers, Business Analysts, etc.
    • Management

    Each of these groups need to know about Defect Management, specifically about the defect repository tool, but at different levels, from everything at the top (Admins) to the bare bones at the bottom (Management).


    Assuming you are the lead Admin, the person putting all of this together for your company, you will need to have a set of documentation for any other Admins working with you, or that come along in the future. This will be the most detailed documentation, but also doesn't have to be a "pretty" presentation, just a document or set of documents detailing all the ins and outs of using the tool as an admin. Think of it as a technical manual rather than a classroom text book. How do you add/remove a user, change their rights, unlock them, change their password? Once you have done that, what do you send them to let them know? How do you fix problems in the system if a user has done something wrong, like moving or deleting folders? How do you set up the different sections of the tool to have it do what you want, or look like what you want? How do you export data, import data? What about all the rest, what the testers do, or the PMs or BAs? Well, there is no need to create separate documentation for the Admins on all of that, since you are doing it for the other audiences anyway.

    Testers and Developers

    Testers will probably use the repository tool more than others, so the focus for them is specifically how to use the tool: how to locate and execute test cases (if you are using your tool for that), how to log a defect from the execution of a test case, how to log a defect on the fly, how to attach screen shots and other documents, how to locate test cases that are assigned to them to retest, etc.

    Developers, on the other hand, need to know their way around test cases and defects, but less on entering them and more to open, read and comment on defects, look at the linked test cases, etc. They generally do not create test cases or create defects, but rather review and comment on them.

    PMs, BAs, etc.

    This group of people are more involved in entering Requirements and Test Cases, and less in actually using them, or in executing test cases or even creating defects. Therefore the focus for this group is at a higher level, and should focus specifically on what they will be doing - most likely entering and modifying requirements and test cases. They will need to know how to mass-import them, and how to enter them one at a time. They will need to know how to manipulate them (move them from folder to folder, etc.), and how to extract them if they need to run metrics on them.


    The final group has almost no need to understand the repository tool at all. They, for the most part, will not be entering requirements, test cases or defects, or executing test cases out of the tool. However, the focus of what they will need to be educated on is the FULL Defect Management process, the Triage Meeting process, expectations coming out of it, what metrics they will be able to get out of the system.

    NOTE that individuals in ANY of these different groups of people may want to know about other areas, but there is no need to create different sets of documentation for each group. They can share! The documentation should be focused on who the key audience is, and should cover everything THEY need to know.

    • Admins - how to MAINTAIN users , and how to RUN the processes and tools
    • Testers and Developers - how to USE the tools
    • Project Managers, Business Analysts, etc. - how to SET UP the tools
    • Management - how the processes WORK, and how to MANAGE them


    Note that all of the work that has now already been done is MOST of the work. Training on all of these documents, all of these areas, is now up to either publication and promotion of the documents, and the storage location of the documents, classroom slide decks and the videos that have been created. AND, the big thing, scheduling in-person or virtual classes to go over the appropriate information with the appropriate groups prior to (preferably) the start of each project or phase of project. As always, if you are doing the training in front of a live audience, in person or virtually, two things. First, KNOW YOUR STUFF! If you have #1 down well, then #2 is easy: be relaxed and comfortable. You should be able to easily answer most (not all, but most) questions that come up, and if you can't, let them know you will find out the answer, and get back to them - and then actually follow up: get back to the entire class with the questions and answers.


    Now that all of the documentation and training has been completed, and your testers are starting to test and enter defects. But what happens if they didn't quite get all the classroom instructions correct, or if they are just aren't quite filling out the defects the way they were instructed? These could be incorrect entries, such as stating UAT testing when the project is only in SIT, or stating the defect was found in Production when the application has not yet been released. It can ALSO be a matter of clarity of the summary/title field. This field is the one seen by everyone, and how the defect is referred to, so it must be clear and concise. If the tester has not entered it in a clear and concise manner, it should be corrected, and the tester needs to be educated, reminded on how best to fill it out.

    All of this is where the defect manager comes in. Before these new defects get to the Triage Meetings to be reviewed and assigned, the defect manager should be reviewing them to ensure the field values are as expected so that time is not wasted with these basics during the meeting. Depending on the volume of defects as a whole, or the velocity they are being added to the system, the defect manager can address this in several different ways. First, they can scan each defect as it is entered into the system, and correct obvious incorrect entries, or address any questionable field values with the tester who entered it with a quick email back to them. A second key method is to regularly run queries on the defect repository, looking at values in fields, and comparison across fields (defect found DURING SIT testing, but found IN the Production environment, probably an issue). Several quick queries run regularly can often catch mistakes that may have slipped through the cracks.

    So, there it is - training and entry verification in a nutshell. Understand what data you and all other entities in the organization need to gather, what that data needs to look like, who needs to see that data (or not see it), edit it or not, and what is required or not, and then make sure that the entry and review of the data is clean and intuitive to use.

    That's it for this blog. The next one will also combine two steps, and look at training users and then verifying that they are entering the defect correctly into the repository.