Spectacular Specs and how to write them!

Editor's Notes

• #3: We’ll go over considerations and structure
• #4: 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
• #5: 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
• #6: 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.
• #7: 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.
• #8: 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
• #9: 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 
• #10: Example of a very simplified Business Overview
• #11: 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
• #12: Example
• #13: Example of a Concept
• #14: 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.
• #15: 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.
• #16: 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.
• #17: 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.
• #18: 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.
• #19: 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
• #20: 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.
• #21: 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.
• #22: If you’re reading the notes – the info above is a tad sloppy  ;-)
• #23: 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.
• #24: 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.
• #25: Example of defining another custom metadata type – see the requirement that amongst records the StageName must be a unique value.
• #26: 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.
• #27: 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.
• #28: Our flow charts have changed. Now it’s numbered and more complex. The actual solution could have been more robust than this.
• #29: Include API names, setting names and all of the logic to describe the flow chart . This is just a partial
• #30: 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. 
• #31: 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
• #32: 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.
• #33: 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.
• #34: 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:
• #35: Example brain dump
• #37: 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?
• #38: 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.