Spectacular Specs and how to write them!
•Download as PPTX, PDF•
1 like•130 views
Roan Bear - Declarative development is fun and powerful, but sometimes implementing business processes requires Apex, and it becomes your job to define the requirements and create a functional specification to pass on to the developers. Good developers will build to your requirements so you’d better make sure they are clear, accurate and comprehensive. Without a well thought out functional specification, you can quickly find yourself in an endless series of QA iterations as those ‘oh, I didn’t think of that’ items crop up, costing you down-time, development time and money. In this session we’ll walk you through the common scenarios you need to consider when defining functional requirements. You’ll learn how to build in extensibility, and how to write a functional requirements document with QA scenarios that developers can use to code and write unit tests against, so that you will get the functionality you need the first time.
Recommended
Recommended
More Related Content
Similar to Spectacular Specs and how to write them!
Similar to Spectacular Specs and how to write them! (20)
More from YeurDreamin'
More from YeurDreamin' (18)
Recently uploaded
Recently uploaded (20)
Spectacular Specs and how to write them!
- 1. SPECTACULAR SPECS AND HOW TO WRITE THEM ROAN BEAR
- 2. #YeurDreamin2019 Spectacular Specs and How to Write Them • What is a Functional Spec • YANYA - Audience • Tools • Business overview • Development Overview • Diagram Overview • Extensibility • Efficiency • Functional Specification • QA • Deployment Steps • Admin Notes
- 3. #YeurDreamin2019 What is a Functional Spec? • It is NOT a technical spec, but… • It IS a detailed description of the functionality that is to be built. • It is a working document • Serves as Documentation
- 4. #YeurDreamin2019 What About Agile? Develop Standups Deploy Iterate User Story Business Requirements Solution Design Collaboration QA UAT Deployment EPIC Who is the Author? Agile success: Domain Expertise, Close working environment, Solution architect Admin/Solution architect: Collaboration and iteration happens during the development of the document
- 5. #YeurDreamin2019 Functional Spec and Agile Recommendations 1. Review whole spec with development and get sizing estimates 2. Identify any underlying infrastructure pieces that need to be built 3. If it has to span multiple sprints prioritize as follows 1. Development Infrastructure 2. Functional pieces that can be broken into functional demonstrations for UAT (user acceptance testing). 4. A functional spec that spans multiple sprints should still have the complete functional picture but should be adjusted to indicate clearly what is to be built for each sprint - for example, add a sprint schedule to the document.
- 6. #YeurDreamin2019 YANYA – You Are Not Your Audience YANYA: Source:Tobias Leenaert http://veganstrategist.org/2016/01/05/you-are-not-your-audience/ Business Owner Developer QA UAT Admin
- 8. #YeurDreamin2019 Business Overview • State the issue and how it’s solved Demonstrates Understanding Defines a contained scope. • Provides context for the developers so that they can contribute. Developers should read the whole document Business Owner Developer
- 9. #YeurDreamin2019 Business Overview Example In order to support YeurDreamin’ Inc’s sales process, key stakeholders must be identified before an opportunity stage can progress. Stakeholders are to be added as Opportunity contact roles, and given the appropriate label. Sales reps are not complying with this requirement because it involves more clicks (oh no!!!) so we are going to make them identify stakeholders based on the opportunity stage they want to set, by presenting them with a validation alert. The Rep will have to revert the stage and add the stakeholder. Then the rep can update the stage.
- 10. #YeurDreamin2019 Development Overview • Where to build & dependencies • General Approach • Concepts, nuances or related code/processes • For contractors: Highlight best practices One trigger to rule them all – code in the class Bulk Safe Commented code REAL unit tests & sufficient code coverage Developer
- 11. #YeurDreamin2019 Development Overview Example • Code will be build in the ’Prestaging’ sandbox. The ABC App must be installed and configured. • Code will be written as an opportunity trigger when the opportunity stage is changed (Before Update) – please do not write the code in the trigger, use the existing opportunity trigger called ‘OpportunityTrigger’ to call the new class/s you will write. • Code must be bulk-safe, commented, and have 95% code coverage. Unit tests should run real tests (have system assert statements).
- 12. #YeurDreamin2019 Development Overview Example • Example of a concept: • Stakeholders: This is the evaluation of the existing OpportunityContactRole records related to the opportunity and the value in the ‘Role’ field. Each opportunity stage (Opportunity.StageName) will require one or more Opportunity.OpportunityContactRole.Role records that will be referenced in a custom metadata type or in a custom setting. • NOTE: a contact may be listed multiple times as an OpportunityContactRole record with different ‘Role’ values. We are evaluating the ‘Role’ for the records, so it’s OK if there are two+ records referencing the same contact. • The mapping of dependencies will be managed in Custom Settings or Custom Metadata Types. Developers: Please review and insert below the name and tactic used.
- 13. #YeurDreamin2019 Development Overview Example • Alert: We would want this to be a validation alert on the page either as a popup or next to the opportunity stage field so that the user can save the opportunity without the stage update. In this way they will not lose any other changes they made. We would like to dynamically populate the missing roles. • Content for validation error: ‘You cannot progress the opportunity stage to {stage value} until you have added the following Stakeholder(s): {role name, role name}. • What is your recommendation for a classic and lightning experience that will work best here?
- 14. #YeurDreamin2019 Diagram Overview • High Level Diagram • May includes pre-process and post-process items for a comprehensive view • Work on this as soon as possible Business Owner Developer
- 15. #YeurDreamin2019 Design Consideration: Extensibility • Add configurability to your solution Configuration not re-coding What might change? • Metadata Types & Custom Settings • On/Off Switch • Record Checkbox field • Audit field
- 16. #YeurDreamin2019 Extensibility Example • Which Opportunities? Type = New Business Or opportunity field ‘Require Stakeholder checkbox’ = TRUE • Which users bypass this requirement? Admins & Finance users Consider any integration users Should we create a checkbox on the user record? Configuration based on user Role or Profile?
- 17. #YeurDreamin2019 Design Considerations: Efficiency • Consider the order of Execution • Don’t build declarative logic just because you can. If you have apex, leverage it and consolidate. • Eliminate declarative if it’s a logical part of the new apex
- 18. #YeurDreamin2019 Functional Specification: Code Execution • Triggers Limits, Async • Batch Code • Ordered records • Dev Console Execution CFCR_Opportunity_Matcher matcher = new CFCR_Opportunity_Matcher(); matcher.MatchOpportunities(new List<ID>{'op1','op2','op3'}); Where op1, op2, op3, etc. are one or more opportunity IDs separated by commas
- 19. #YeurDreamin2019 Functional Specification: Code Execution • Code should be written as an opportunity trigger when the opportunity stage is changed (After Update) – Use the existing opportunity trigger ‘OpportunityTrigger’ to call the class. • Developer, please indicate class name & test class name below
- 20. #YeurDreamin2019 Functional Specification: Records • Document these decisions What records are subject to this functionality What are the exceptions (not apex exceptions) If there is a mechanism or on/off switch • Be careful of language that may confuse developers: Trigger, Exceptions.
- 21. #YeurDreamin2019 Functional Specification Example • Code applies to Opportunities that require stakeholders: • Criteria is: ( (1 OR 2) AND 3) • OR 1. Opportunity.Type is referenced In Custom Metadata (put finalized metadata name here and field to reference) 2. Opportunity.Stakeholders_Required__c is True • AND 3. Running User Stakeholder Bypass field (Stakeholder_Bypass__c) on user record is False
- 22. #YeurDreamin2019 Functional Specification: Global Settings • Build Extensibility Here Custom Settings or Custom Metadata Types • Why not let the developer build the fields? Field Names, API Names, Description, Help text • Developer should update what they built
- 23. #YeurDreamin2019 Functional Specification: Global Settings • Eligible Opportunities (Custom metadata or setting) • Field: Label – This is a required field, not evaluated by the code. (40 char limit) Initial value: Default • Field: Opportunity Type Label: Opportunity Type API: Opportunity_Type__c Type: Text 255 Description/Help: Semi-Colon delimited text field that lists values in the Opportunity Type field that indicate stakeholders are required. Initial Value: New Business • Developer: Please list what was built
- 24. #YeurDreamin2019 Functional Specification: Global Settings • Opportunity Stakeholder (Custom metadata or setting) • Field: Label – This is a required field, not evaluated by the code. • Field: StageName Label: StageName API: StageName__c Type: Text 255 Description/Help: The Opportunity Stage MasterLabel that is being set DO NOT ALLOW DUPLICATE LISTINGS, This field corresponds to the value of the MasterLabel for the opportunityStageName object • Developer: Please list what was built
- 25. #YeurDreamin2019 Functional Specification: Global Settings • Opportunity Stakeholder initial values StageName (unique value) Role (Semi-Colon Delimited) Qualification Business User Needs Analysis Business User Value Proposition Business User; Evaluator Id. Decision Makers Business User; Decision Maker; Evaluator Perception Analysis Business User; Decision Maker; Evaluator; Influencer Proposal/Price Quote Business User; Decision Maker; Evaluator; Influencer; Executive Sponsor Negotiation/Review Business User; Decision Maker; Evaluator; Influencer; Executive Sponsor; Technical Buyer Closed Won Business User; Decision Maker; Evaluator; Influencer; Executive Sponsor; Technical Buyer
- 26. #YeurDreamin2019 Functional Specification: Description • Depending on complexity may have more than one sequence and flow chart broken out into logical parts. • Numbered Flow Chart • Use labels and API Names • Identify Dynamic Elements • Tie breaker rules
- 28. #YeurDreamin2019 Functional Specification: Description 1. Opportunity is updated 2. Opportunity Type matches global setting (add name here) 1. Yes go to 3 2. No go to 7 (end) 3. Has Opportunity.StageName changed to a value listed in a ‘Opportunity Stakeholder’ custom metadata StageName record. 1. Yes go to 4 2. No go to 7 (end) 4. ..5.. 6 Display Error Dynamically
- 29. #YeurDreamin2019 QA • Helps you make sure you haven’t missed anything • Audience • Do one round yourself to validate • The level of detail is driven by the audience Business Owner Developer QA UAT Admin
- 30. #YeurDreamin2019 QA Testing • How to Test: • Describe the use of the code snippets the developers created for the dev console • Audience Dev console access • Do one round yourself to validate
- 31. #YeurDreamin2019 QA: Data Setup • Audience Do they know how to create an opportunity Do they know how to create opportunity contact roles? Do they have permission to do so? Any fields to set to make sure it’s a test and send off notifications etc? • What minimum fields are required? • Test as a specific user? • Include API Names
- 32. #YeurDreamin2019 QA: Review Global Settings • Fill This in after the coding is complete • Include instructions & screenshots
- 33. #YeurDreamin2019 QA: Test Scenarios • Number your test scenarios (steps should be numbered bulleted lists) so that they are easy to reference, you can even reference parts of the flowchart if that’s helpful • Positive and negative tests • Start with a brain dump – what are you testing for • Include Data setup Action to take (user actions) Expected outcome (alerts, field updates etc) Test Results • Your QA section may be longer than or as long as the rest of the document.
- 34. #YeurDreamin2019 QA: Brain Dump Examples • Brain Dump for testing: Should not fire for new opportunity Created as prospecting stage, created as closed/won Should not fire for ineligible opportunities Not new business (as configured) Checkbox not set Should not fire for bypass users Should not fire on opportunity update without stage change Should fire on opportunity stage update if opportunity contact role is missing – test against all settings
- 35. #YeurDreamin2019 QA Test Example Positive test for update to stage ‘Qualification’ • Qualification Stage Validation Create an opportunity stage type ‘New Business’ Stage ’Prospecting’, amount $100 & Save Update stage to Qualifications & Save Expected Result: Validation error: Stage Qualification requires a ‘Business User’ contact. Actual Results: _____
- 36. #YeurDreamin2019 Deployment Steps • Build this out as you’re working on the spec • Pre-Deployment Review opportunities missing ‘Type’ value • Deployment Deploy change set New fields, apex code Page layout adjustments Check reports? • Post-Deployment Steps
- 37. #YeurDreamin2019 Admin Notes • What considerations does an admin have to keep in mind? • Opportunity stage changes • Opportunity bypass formula field • User bypass field • Check reports Admin
- 38. #YeurDreamin2019 Join us for drinks @18:00 sponsored by Community sponsors: Roan Bear Roan Bear Consulting @RoanBear https://www.linkedin.com/in/roanbear NonProfit-track sponsor: Order of Execution: https://sforce.co/1hUzTY2 Gliffy: www.gliffy.com Object Reference: https://sforce.co/1GWbOdt
Editor's Notes
- We’ll go over considerations and structure
- It is NOT a technical spec, it does not tell the developer how to code the application (for example, defining class names, queries etc.) It is a detailed description of the functionality that is to be built, It may recommend approaches (to be discussed with dev’s) down to field-level details. It may be used for business owner sign-off of scope. In my view, It is a working document, and is not ‘finalized’ until the code is complete - because, depending on the complexity of the project, as the developer works on it, or as you test it, you may need to make revisions for edge conditions or missed scenarios. For that reason I like a collaborative platform such as google docs for delivery and during development. Serves as documentation post deployment
- Agile: Agile works best if you have a team in which all members have domain expertise and are available for lots of meetings such as daily standups. It’s also good for an iterative process or if you’re not sure what the final output will be Some of the problems that I’ve seen is that user stories may be too high level and leave the details to the developer team, so a developer team without domain expertise may not build a solution that takes in mind all of the other dependencies of the org. One time I saw a team build functionality onto a duplicate field they created rather than using an existing one. What is often missing in this process is the architect – this is the person (A senior admin or consultant) that translates the business requirements into a more robust ’user’ story or adds the missing details. Functional specs If you know what you want to have built, and have the domain expertise write a functional spec It is more work, but you will get a final product that does what you expected. It’s still collaborative, but can reduce iterations, and save you a ton of standups You could piece it out into user stories if you’re are working with a team that does agile development with that development framework
- Review whole spec with development and get sizing estimates - how many sprints does it have to span Identify any underlying infrastructure pieces that need to be built, for example if a custom routing engine or async system is required – or refactoring code If it has to span multiple sprints prioritize as follows Development Infrastructure Functional pieces that can be broken into functional demonstrations for UAT (user acceptance testing). For example, built the objects and fields first, so that you can use dummy data to demonstrate reporting and functional flow. A functional spec that spans multiple sprints should still have the complete functional picture but should be adjusted to indicate clearly what is to be built for each sprint - for example, add a sprint schedule to the document.
- YANYA: You are not your audience. Tobias Leenaert (Belgium) http://veganstrategist.org/2016/01/05/you-are-not-your-audience/ There are also Youtube videos by him. Who is your audience & what do they know. This will drive the the level of detail you need to provide in your spec. Business Owner, do they use salesforce? Can they do testing/validation? They may use the document to validate functionality and to to QA and as a reference for what was built. Developer, are they a contractor or internal? Do they use the UI? (I’ve known developers that had never created an opportunity through the UI). Use the document as the basis of the build, and QA scenarios can be used to document bugs or highlight missing unit tests. This document ends up being a type of documentation you can reference (in fact I’ve seen parts of the functional spec used as comments in the code) QA/UAT, is this a specific person or team? Internal or external? You? - follow QA scenarios to test functionality as well as running any other tests required. Admin – this is the person who will own the code and maintain it, particularly if you’ve build configurability into the solution, but in either case they need to understand how org changes may impact the code.
- Tools Object Reference: https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_list.htm https://sforce.co/1GWbOdt Template: Your company may have a branded look/feel. Since I like working in google drive for these types of projects I don’t really worry about that and generally no one else cares if the spec looks pretty. If you are from a consulting company I’m sure they will care about how this document is presented so professionalism never hurts. If you find yourself doing a lot of these, you may want to create a template for future technical specs, you may even find parts of the QA content repeatable (for example, create a new lead and set these required fields). Collaborative Environment – Google docs is great. Box notes… Diagramming the process is invaluable, first to make sure you have not missed anything and have thought out all of the scenarios, and secondly to help the business owner and developer visualize the data flow. Text, particularly for a complex project, can really benefit from the visual. It also lets you number the decision trees and data updates so that the text steps can align to the image. For larger projects, you might build a high-level diagram, and then have additional drill-down diagrams. Most of the diagrams - at least the high-level ones- should be created during the discovery part of the project before writing the functional spec, and used to validate requirements, and ask any questions that were exposed during the diagramming process. Most recently I’ve been using Gliffy, it can be added to confluence which is a tool we were using internally. Folks also like Visio. A hosted/shared diagramming solution is nice. https://www.gliffy.com/pricing
- The purpose of this section is to state the business challenges and how this functionality solves the problem and any specific nuances. This section does a couple of things Demonstrates that the author understands the requirements Defines a contained scope. More importantly for me - provides context for the developers. If you are working with a good developer they won’t just code, they will think. They will recommend improvements to the functional spec and question you if something was overlooked or doesn’t make sense. The product is always better when the whole team is thinking critically about it, so this section is very important for the developer because otherwise they would be working in a vacuum and not be able to think critically about what they are building. For this reason emphasize that developers should read the whole document
- Example of a very simplified Business Overview
- Indicate where to build- which sandbox etc. Indicate any dependencies in the sandbox, such as an installed and configured 3rd party package General approach to code such as: Batch/trigger Extensibility approaches Dev console one-time runs Call out any specific things that developers need to understand upfront conceptually, for example nuances in the data, or other related code/processes If you are working with a contractor or a person unfamiliar with your org or best practices it’s always good to mention the following If the code involves a trigger, do not code in the trigger – write new classes that are called from an existing trigger - best practice is one trigger per object (the exception to this is triggers that are part of managed packages) All code should be bulk safe Code should be commented Unit tests need to test the code & sufficient code coverage
- Example
- Example of a Concept
- Here we are highlighting some functionality we need built but we need advice on what will work best. You may have a specific request from the business owner for a validation experience, for example a window alert, that may more costly to implement than inline – and the developer can provide feedback that you can take to the business owner to discuss.
- I like getting right into a diagrams as soon as possible so that the business owners can see what we are trying to accomplish. If the code is complex this is the place for high-level diagrams A diagram may also explain a process that is not being coded, but is done prior to the code being generated, for example - how a user might create an opportunity , or steps they may take manually after the ‘code’ is done executing.
- In your design think about extensibility. It’s best not to hard-code things that might need to be updated over time, for example a user Id, Role Name, Campaign ID, timeframe etc. The idea behind this is to add ‘configurability’ to your apex code so that it’s possible to update There are a couple of ways in which this is easily accomplished by using custom settings or custom metadata types. I typically let the developer decide how they would like to approach this, and ask them to document their approach including object names and so on, so that they can be added to the change set. Custom metadata types have the added advantage of being able to be deployed with change sets, but keep in mind that the data referencing IDs may need to be updated as part of the deployment steps to reflect the ID in production. Referencing these objects in code doesn’t ‘cost’ you anything in terms of efficiency, but it does save you development and QA time down the line, as you simply update configuration as compared to a code update which requires re-coding, adjusting unit tests and QA. For me, anything that might change is moved into the extensibility category. Consider whether for any reason you want an ‘off’ switch in the code, and if so, add that in as a field and into the flow chart and functional spec. You may wish to tag the records with a checkbox (formula or not) to indicate inclusion or exclusion from code execution, in addition to other criteria. You may need an audit field to indicate when a certain operation updated a record.
- We’re going to use two mechanisms to indicate eligible opportunities. We’ll look at the ‘Type’ value which we’ll manage in custom metadata/settings, and we’ll also use a formula checkbox for other cases where we want to require stakeholders and the opportunity doesn’t meet the Type criteria. The formula field will be managed by the admin. Finance and admin users can progress stages without requiring stakeholders. If it’s a small org we may just want to have a user field. If it’s profile specific (depending on how the profiles are setup) – it maybe we manage this with hierarchical custom settings and so on. But in this case we’ll just use a user checkbox.
- Consider the order of execution where triggers fire workflows fire triggers fire processes etc etc etc…. While it’s true that some of the items in a functional spec can be accomplished with declarative logic - do it in apex if it’s directly related to the code being written………. Unless the declarative code would fire under other circumstances or it needs to be modified. This will save optimize CPU usage, and if you’ve ever gotten the CPU exception you’ll know what I’m talking about. As much as declarative is fun and empowering, it’s inefficient to use it when there is already related Apex.
- If the code is a trigger, indicate so here. By a trigger we mean, that if something specific happens on a record, this code should execute for that record. You may even have to set it up as an asynchronous update depending on the load already running on that object. If the update doesn’t have to be immediate - then consider using batch code. A batch can be run often, for example every 15 minutes, or once a day. Batch code is more efficient. If this code is to run as a batch indicate so here and also how often it should run. You may want to add configuration for batch size as a way to manage limits if you are working in a very large complex org (devs can give you feedback on that) . Indicate if there is an order in which the records in a batch should be run - for example oldest to newest, and which field the oldest to newest is based on (createdate/ lastmodifieddate, other field) If you are running a batch, I like to request a mechanism here I can run a single record or string of records real-time through the developer console, so ask for the code snippet you would use to do so and the syntax, as well as code snippet to use to trigger the batch. We do this because sometimes there is a record we want to process and don’t want to wait for a batch to run. Having this code snippet is incredibly helpful to speed up the QA process where you can stage a set of records and immediately process them. Highlight in RED that the developer should add the code snippets to the document in this location. Example of a code snippet
- An example of indicating how the code will run and soliciting information back on the names of what was built so that you can add that into your change set and deployment steps.
- There are almost always exceptions. This section either validates that this code works on ‘all’ of the records, for example, opportunities, or a subset. Having this section makes you think about exceptions and possibly build in a mechanism to restrict the code to specific records. For example, only run on opportunities where the type <> Renewal, or, in a trigger situation for example, where the running user’s profile is not system administrator. This data is repeated in the functional details but it’s good to call it out in a distinct section so that it’s easier to understand, and so that you benefit from having had to think it out. Your language may be confusing to developers so be careful. If you say X triggers the code, they may thing you literally mean a ‘trigger’, similarly when I discuss a business exception they may thing apex exception.
- If you’re reading the notes – the info above is a tad sloppy ;-)
- This is where I define the settings that this code will require in order to build in extensible configuration. I typically define the fields, add a description and provide the default values we’ll be using in that sandbox. I like to take the initiative and name the fields and description text because I’ve found that while developers may use pragmatic names (syntax), sometimes they are harder for end-users to understand. Adding description text to the fields also makes them easier to understand. There may be different configuration sets depending on the complexity of code. Add a section in RED requesting that the developer add a description her of what they actually built. If you know what you want specifically, you can also build this out ahead of time and provide the developer with the information. If you require specific records exist in the sandbox in order for the code to run, create them now and that way you can reference them in the custom settings/meta data. I might also highlight some logic that may be repeated over time, for example, if there is a tie-breaker amongst multiple records, and it’s referenced in different places of the functionality, that is something they can code once and call from multiple places. While it may be repeated in the functional steps, highlighting that there is a repeating element here as a global behavior helps solidify the logic.
- Example of defining a global setting and ONE of the fields (there would be more defined) Don’t write code that evaluates the label field in code unless you are certain you will always be within 40 characters, which is that fields’ character limit.
- Example of defining another custom metadata type – see the requirement that amongst records the StageName must be a unique value.
- Here is a table with the initial records that need to be created. If I’ve build the metadata type or custom setting I would have set this up in the org pre-coding as well as listing it here. We haven’t listed stage 1 (prospecting) or Closed Lost because stakeholders are not required for those stages This is simplified. A more complex business logic might require a minimum # of stakeholder roles amongst the list instead of all of the roles listed.
- You may have more than one of these sequences depending on the complexity of the code. If so, ideally you’ll have broken it down into clearly identified ‘names’ describing the functionality, such as, ‘Create renewal opportunity’ After a brief description provide a numbered flow chart and then use bulleted text to break down and provide the information the developer needs. Be very clear on any conditions that must be met, and consider tie breakers as well. Is it for new records only? What fields values should be set on the object or what related objects must there be? In the description provide information on the object, the label and the API NAME. Make it easy for the developer to code, and in this way you can also make sure they are referencing the correct field.
- Our flow charts have changed. Now it’s numbered and more complex. The actual solution could have been more robust than this.
- Include API names, setting names and all of the logic to describe the flow chart . This is just a partial
- At this junction we must think about the audience again. Writing QA scenarios is a pain - but it always helps me make sure I didn’t miss any logic in the functional spec so it’s really helpful to do before turning over the document to the developer - although, admittedly, I’ve done an initial review with the developer before being done with this section. You should do at least one round of testing because you should test to validate the developer built what you asked for - so writing out QA scenarios is a roadmap for your testing. While most developers write unit tests based on the requirements, the QA scenarios would help to identify scenarios they may not have thought of to test, or provide steps to recreate should there be a bug. Who is doing the testing will determine how much detail you need to build into this section. For example, if the people doing QA are rarely in the UI or don’t know how to use the dev console, or are a third party and unfamiliar with the nuances in your org, you’ll need to document more basic data setup and highlight required fields.
- This is where you take the code snippets the developers wrote for you and re-post them with better instructions, possibly including how to get a record’s ID and how to get to the developer console and run code. The level of detail depends on the audience. Consider? Can all of the testers access the developer console? If not, what setting is needed Here are the permissions - create a permission set and assign to users. https://salesforce.stackexchange.com/questions/108414/what-permission-you-need-to-have-developer-console-work You may add Re-usable text to your template describing accessing the developer’s console
- Typically I’ll create a section about setting up the data. For example, if you are creating an opportunity that is subject to this code, what fields need to be set on it. Does it require any related records? And so on. This section helps an end-user understand how to set up data for testing so that you don’t have to repeat that description for each scenario. You will want to provide instructions on creating any records, and review any required fields in order to specify how they should be populated. In an example of how to setup data include API names in order to make it easier for the developer. Do you need to create data as different user profiles/roles? If so indicate what they are or specific users and how to ‘login’ as them for testing.
- This section will be filled in after the coding is done unless you created the custom settings/meta data records. This is a review, typically with some screen shots of the values and how they will impact the code and what they mean. Sometimes you can just repeat the descriptions again in this section so it’s closer to the QA part of the project. You may want to provide a link to the custom metadata in the sandbox, or instructions on how to navigate to it.
- When writing QA scenarios try to cover all kinds of situations and ideally try to break the application. Sometimes I break it down by functional area and then track the variations. Determine if you need to test as an specific or set of end-users or if the user doesn’t matter. Before writing these I like doing a brain dump - a short bulleted list that covers the scope of what I want to test. Then I can write the actual scenarios out one at a time. In the QA scenarios I include field API names in case I have a failed scenario - then I can send the failed scenario to the developer and the developer will have an easier time validating and fixing the error. Ideally you number the QA scenarios and use numbered bulleted lists for steps, which also makes them easier to reference. Components of a QA scenario are Number and Scenario Name What are you testing Steps for the test Expected Results Example Test 1: name here based on what I build In this scenario we are testing abc Steps: Create an opportunity Set the following fields Do the following Run test Expected result:
- Example brain dump
- I put this after QA scenarios because it can get lost if stuck in between items and it gets referenced after QA is done. I also build this out as I’m writing the functional spec. If I have built anything for the project (such as fields, workflow rules, custom settings, page layouts) I am inserting them into a change set as I go. Make sure that anything the developer built is added to the change set. Think about the following: Are there any pre-deployment steps such as data adjustments that will be required. Do you need to create any records or back populate anything? What are the deployment steps? And in what order? Change set name Field visibility adjustments Fields to add to layouts, or custom report types Custom settings to populate or metadata types to adjust based on production data If you are using a batch, a step is to schedule the batch What are the post deployment steps? Schedule the batch?
- This section is really about integrating this new functionality into the institutional knowledge of the system admins moving onwards. Some code requires maintenance or awareness of how changes in the org may impact this code. For example - you may have a list of profiles that are treated differently by the code, in that case, profile changes made to the org must consider this code, and configuration should be updated to reflect any changes in profiles. I had a customer with complex SLA code based on user roles - they updated all of their roles but didn’t update any of the custom settings for the SLA code, so all of the SLA code stopped working. If you are a consultant, it’s the company’s admin’s responsibility to document this dependency, so hand off a comprehensive section on this so that your back is covered if they mess it up. Even though they likely worked with you and signed off on all of the functionality and understood the implications of this code, this section is important. In our example changes to opportunity stage names or opportunity Type field, and exempted users are to be considered. Explain the opportunity Stakeholders required checkbox formula field. If you are the org’s admin - write it up anyway- people come and go in organizations so it’s a good place for you to think this through, and then integrate it into the org documentation you are supporting.