Functional and Technical Documentation for Salesforce Projects: What’s the Difference?

Documentation is a crucial part of successful Salesforce projects. In this article, I’ll introduce a set of documentation artifacts that are essential for any healthy project, big or small. By the end of the article, you should:

• Understand the difference between technical and functional documents;
• Be able to identify high-priority technical and functional artifacts;
• Have access to a set of tools and resources to shrink the time spent on producing these documents.

Ensuring this set of critical artifacts is included in your project can save time, budget, and headaches down the road.

Functional and Technical Documentation

Each Salesforce org that you manage should have a set of coherent functional and technical documents to support it.

• Functional documentation describes the business and the business requirements that the technical solution supports. It defines the ‘why’ behind the solution.
• Technical documentation describes ‘how’ the solution meets the business requirements. It grounds the technical decisions and tells readers how the system is intended to work.

Functional and technical artifacts are different but equally important in forming a full picture of the delivered solution that is concise, contextualized, consistent, and connected.

Pro tip: You can increase the value of your documentation by ensuring that your technical artifacts are tethered to the functional requirements that they support. Check out the functional decomposition methodology to learn how to relate solutions to requirements.

Below, I’ll unpack the most crucial functional and technical artifacts to include in your Salesforce implementations.

Functional Artifacts

Functional artifacts outline the problem to be solved and define what value the solution should bring to the organization. Functional artifacts critical to Salesforce implementation projects include:

• Business Glossary: Outlines key business terminology to help project teams develop a correct and cohesive shared language with the client. Later, you can use the glossary to help document Salesforce label changes.

Example:

• Org Chart or Stakeholder Map: Describes roles and their hierarchy in the business. Organograms can be used to help define the role hierarchy and outline to-be record ownership during solution design.
• Conceptual Model: Outlines the key (functional) entities and their relationships before the technical data model is developed. Conceptual models are normally drafted during the discovery phase and can be used later to validate the logical model or ERD; they don’t necessarily need to conform to Salesforce objects.
• Functional Decomposition Diagram: Tells the functional ‘story’ of the business, highlighting the key business functions and processes. Ensuring each lower-level process outlined in the diagram has at least one user story can help to ensure your corpus of user stories is complete.
• Process Flows: Outline the key business processes to help support a general understanding of the business. Universal Process Notation is the recommended notation style for Salesforce projects.
• Personas: Outline the in-scope user groups that the solution will support. Personas provide a user-focussed structure to requirements and help to ensure that the solution provides demonstrable value to real people in the business.
• Epics, User stories, and User Acceptance Criteria: Outline requirements that need to be solved in a digestible, user-focussed format, as well as the criteria used to validate if the solution meets the requirement. User stories should follow the “INVEST” framework, and user acceptance criteria can be structured using “Given, When, Then” statements to enhance quality.

Technical Artifacts

Technical artifacts outline the to-be state and delivered solution, helping readers understand how the solution supports the business requirements. Technical artifacts critical to Salesforce implementation projects include:

• Narrative Solution Overview: Provides a plain-language summary of how the solution supports the business requirements, including key features and design decisions, products and tools, and limitations.
• Logical Model: Outlines the objects and their relationships. This ERD should conform to the conceptual entity relationships from the conceptual model but should be amended to reference Salesforce standard and custom objects.

Pro tip: Annotate your logical model with anticipated data volumes, the suggested Organization-Wide Default (OWD) setting for the object, and the intended record owner to improve its utility.

• System Landscape Diagram: An as-is and to-be system landscape diagram should be utilized to outline the current landscape of tools and technologies, as well as the future-state vision of how Salesforce will interact with other systems.
• DevOps Pipeline or Release Management Diagram: Outlines your release management strategy and processes, including the relevant environments (sandboxes) used in your development process. Maintaining a clear DevOps pipeline is critical to ensure quality throughout the development lifecycle.

(Simplistic) example:

• Security and Sharing Overview: Provides a plan-language summary of the object permissions and record access strategy utilized in the org, including reference to any data security tools, protocols, and mechanisms.
• Automation Specs: Provide a visual representation of automation in the org, including the trigger context and any invocable actions so that readers can quickly and easily understand the automation landscape and how various pieces of automation may influence or support one another.
• Metadata Dictionary: Provides an overview of the metadata assets of an org, including definitions, data types, field-level visibility restrictions, and security classifications.

Save Time With Templates

Every implementation project comes with a set of constraints. These may be related to delivery timeline, budget, competencies, and commitment to agreed processes. When resources get tight, teams should do their best to stick to the process. The key is to have a reliable strategy to help your team deliver quality documentation efficiently.

There are myriad tools in the Salesforce ecosystem to help standardize and templatize key documents:

• Salesforce Architects has a treasure trove of pre-created diagrams, models, and frameworks freely available to you.

Pro tip: Open certain diagrams and data models in LucidChart to convert them into your organization’s branding. Save the new document as a template to use as a starting point for every new project.

• LucidChart and LucidSpark have numerous Salesforce-orientated and platform-agnostic templates and a Salesforce shape library to expedite the creation of beautiful diagrams.

Pro tip: Salesforce integrates with LucidChart, allowing you to import information from your org directly into Lucid, such as your object schema for faster creation of data model diagrams.

• Don’t forget to generate a Salesforce Documentation Strategy to outline best practices and standards for your team to follow when generating new artifacts.

Pro tip: Use this Salesforce Documentation Strategy template to quick-create your strategy and help your team improve documentation consistency and quality.

Your team can also “shift left” the effort spent on documentation by templatizing the key artifacts outlined above. This will ensure consistency and correctness of your corpus of documentation for each project and save team members time in generating new artifacts.

Summary

Documentation generation takes time, but a focused set of high-quality documentation will always save time in the long run by helping your team understand, maintain, debug, and enhance your system in the long run.

Before you embark on your next Salesforce project agree upon critical artifacts with your team and set up templates to help make your documentation better and faster.