2. Document your Org – Principles

Learning Objectives

After completing this unit, you’ll understand:

  • Why documentation matters
  • The principles behind documenting your Org
  • Capturing HOW the parts of the Org/business supported by Salesforce work
  • Identifying and linking WHAT was changed in Salesforce to support it.
  • Linking existing and new documentation in context of your Salesforce Org model to describe WHY you changed Salesforce.

Why documentation matters

When Salesforce was tactical and had a narrow scope developing with limited or no documentation was (probably) acceptable. It was not recommended, but it was the norm. Now Salesforce is a strategic app that is critical to the ongoing operation of the organization. Having no relevant documentation is probably negligent. It certainly puts the organization at huge risk.

An implementation with no clear documentation of what has been configured – and (most importantly) why – means that it is very difficult, if not impossible, to support, maintain and improve. Every Org is constantly evolving. This can be incremental changes to tweak and improve the user experience, all the way up to major change projects to implement new functionality, such as Lightning, CPQ or Einstein. All these changes need to build on the existing Org. To do this with any level of confidence requires decent documentation of what has been built before.

We are all facing the issue of poorly documented Orgs. We make changes to an area of the Org but don’t take the time to document what and why, because of the need to finish quickly. Then 6 months, 6 weeks or even 6 days later we want to make further changes to the same area, but we can’t remember what was done. So now we have hours of investigative work to do. This is documentation debt.

Documentation debt has a real impact. One of the reasons for Salesforce’s huge success is that it is so easy to configure using drag and drop. It doesn’t require lots of coding. But documentation debt kills that agility.

Even the simplest change could potentially impact different areas of the business. Currently, one option is to look in Salesforce Setup and do a ton of detective work. There are so many configuration options that the risk is that you miss something, break the Org and stop the business operating. Another option is to create new customizations rather than change the existing ones. This bloats the Org with multiple similar objects, fields, flows and validation rules, process builder workflows, etc.

For those of you with complex and older Orgs, the concept of ‘Documentation Debt’ killing agility is nothing new. There is often a legacy of configuration and Apex code delivered by 3rd parties with little or no useful associated documentation. Once again – documenting what has been done – and why can bring huge benefits for agility.

The principles behind documenting your Org

It is not realistic to look at your Org, which may have 10,000 or even 75,000 metadata items, and try to work out what everything does and document it. You know you would never get started. Just focusing on one area – i.e. all Apex Classes or all Process Builder Workflows – is also challenging as the customizations are so interconnected.

The best approach is to come at it from an operational perspective. Think of a Salesforce object and focus on how it works. For example, the Opportunity or Case object. Think about the lifecycle of an opportunity – from raised to closed won, or a case – from issue to resolution. Document that as a process diagram and find all the customizations related to making it work. Then take another area, “the lifecycle of an case” and document that.

So we have a simple 3-step approach that is practical, achievable and helps you make measurable process.

  1. HOW : How does this part of the Org/business work?
  2. WHAT : What did you change in Salesforce to support it?
  3. WHY : Why were changes made and where is the documentation that describes why and how you changed Salesforce?

 Here is a process diagram that describes that process. In the worked example you will be following this process to document the lifecycle of the Opportunity object

First you need to work out what area to focus on. So, take a small area that’s relevant to the work you are doing. You probably have a very clear view of the top 3 hit list. Here are some examples that we hear about from customers:

  • To migrate to Lightning we need to understand how to simplify page layouts, validation rules and automation, and fix the migration issues
  • Users are complaining about slow page loads and busy page layouts so we need to look at that Object and how to reduce the fields on the page layouts
  • We’ve reached field limits on Objects so need to work out which we can delete
  • So many of the reports have never been used. Which ones can we delete?
  • We are working through all the Apex triggers trying to understand their interactions and if they are all used
  • There are multiple process builder workflows that all seem to do the same thing

In this training we will map the Opportunity lifecycle as a process diagram; from qualified lead to closed opportunity. This is the HOW.

We are then going to create links from each step in the process diagram to the things that were used in Salesforce. This is the WHAT.

And then for each link we make we are going to add documentation. The WHY.

Don’t worry. This is a lot easier than you think.

Step 1. HOW

First the HOW.  This is all about understanding how the business operates and is best described as a simple process diagram. It is how the users use Salesforce to get their job done. It is how that automation or integration works behind the scenes.

We are going to use the Opportunity lifecycle – from being raised to closed won (or lost) as the process we are going to look at.

Landing pages

But before you start creating a process diagram for the Opportunity object process we need to create a top-level landing page – a graphical folder structure if you like – where you can put ALL the different process diagrams and data models you will be drawing over time as you document more and more of your Org. Elements supports the concept of a process map that is a hierarchy of diagrams. So use the process map like a folder of process diagrams. There are advantages to this rather than having lots of discrete diagrams. You are only managing one map, therefore managing access rights, governance, version control, reporting and branding is far simpler.

We’ve seen different approaches for landing pages

  • An overall company end-to-end process or value stream. This sometimes takes a while to get agreement on if it doesn’t already exist. But is is very valuable because every process in the company hangs off it somewhere.
  • A series of activity boxes each of which is a mini end-to-end process; “issue to resolution”, “recruit to retire”, “quote to cash”.
  • A simple set of activity boxes for each lower level process diagram, so it is essentially a set of menus or shortcuts

Below are examples of each type of landing page.

Option 1. Top Level operational diagram. This is the flow of high-level activities showing the core value stream of the operation with individual boxes housing the support processes. If you have this kind of view available – or have the right stakeholders to help you create it – it’s our recommended approach. If you can’t start with this picture, at least keep it in mind as it’s where you would hope to end up if you use this approach in the longer term.

Option 2. Catalog of “End to End” processes. This is a common way of describing processes in an “IT project” context. “issue to resolution”, “recruit to retire”, “quote to cash” ..etc. This is really useful when you do not have the time get agreement around how option 1 should look. The example below shows using “Image mode” for the activity box theme. This makes it more visual and when you hover over the image – the text underneath becomes visible. But you could just as easily write “Develop and Close Sales” or “Develop new product” as the text in the activity box. The inputs/outputs in this context are optional. Whatever works for you. It’s about communication, context and getting everyone on the same page.

Option 3. Using an existing folder structure. You may have existing documentation and process content in a set of folders. We get asked “how can I save my Elements maps in folders”. We would recommend moving to a process focused structure (like Option 1 or 2). If that’s not an option, simply create a top-level diagram that replicates your file folder structure for content. While it re-enforces functional silos and misses out on delivering the value of cross-functional visibility, if you absolutely have to stick with it – it’s no worse than where you are today.

Mapping processes & notation

Mapping processes can feel daunting, especially when you start talking to IT teams who often use a complex modeling notation.  For business process mapping Elements supports a simple notation that has been proven in 1,000’s of projects over the last 20 years.

Diagrams can be drawn in any format or style but this approach really works:

  • Draw the diagrams in a simple left to right process flow aiming to have no more than 8-10 process steps per diagram, called activity boxes
  • The activity box is a single, simple building block to show what is done and by whom. It is all you need. You don’t need lots of different shapes. Trust us.
  • Any activity box can have lower level “child diagrams”. This makes it easy to keep each diagram simple and easy to read with the detail in the lower levels.
  • The audience for these diagrams are
  • end users; get agreement on optimized processes and use them as training embedded inside Salesforce objects
  • admin/developers; clear view about what operational processes need to be supported by the customizations
  • compliance/auditors; in regulated industries the process diagrams support regulatory compliance
  • management; the processes highlight departmental handoffs and also the key metrics that should be measured

This video is also in the detail of Unit 3 – but if you’re more of a video person and you want to have Walter explain some of the principles and show you, you can watch the 9 minutes now and see how it’s done. Pick up the text again 1 page down. Otherwise you can skip the video until Unit 3 and read on…

if you didn’t watch the video, read from here……

Process mapping notation

The cool thing is that there is only ONE shape to worry about. With just this notation you can describe any process, no matter how complex, in a way that everyone understands – without any training.  

So the way of thinking about the process diagram is this; “What happens in terms of actions (verb and noun) which together produce the desired outcome. Why do we start it and why do we complete it (input/output)? Who carries these steps out (role/resource – can be human or system). How is each step carried out in detail (drill down to child diagram – blue corner) or link to supporting documentation – paperclip).

Here are some hints on using the notation when designing process diagrams:

Input/output: The lines between activity boxes show the triggers and outcomes.  Every activity box must have lines connecting them. And every line must have line text. If the activity is “Process Invoice” then try to avoid calling the output “processed invoice” but instead try to be more specific. Is it “approved invoice” or “validated invoice”?

What happensIt starts with a verb: Create email, Raise opportunity, Triage and route case, Assign task, Win order, Onboard team member.  Try to avoid the words “manage” or “process”. Get more specific.

Resource: One or more resources can be attached to an activity box. They describe who is responsible for an activity i.e. Salesforce Admin, Customer Success Manager, but can also be a system i.e. Salesforce, Pardot. They are an alternative to swim lanes and keep the diagrams tighter.

Drill down corner: The corner shows that this activity has a lower level diagram

Links: The paperclip shows that there are links to attachments – notes, images, URL links etc. These are displayed in the right panel

If you watched the video – pick up again here…

To make this training easier, we have provided you with process map that you can copy.  There are a number of maps you can copy for your own use in the Example Maps Space

Below is the top level diagram. If you click on the drill down corner which is the top left of any activity box you will “drill down” to access a lower level diagram.

The Opportunity process diagram

Here is the process diagram that describes the lifecycle of an opportunity. This is the drill down from the top level diagram.   You can see that each step also has drill downs to lower level diagrams. There is no limit to the number of levels that you can drill down.

Now you can understand the opportunity process that we have developed for you.  Your process is probably very different, so you can edit your copy. It is simple drag and drop.

The process diagram that you see above describes “a process”. It may not be the process that everyone follows. It may not be the process that everyone believes happens. The power of process mapping is getting shared agreement and then communicating the process to everyone. As you go through the mapping you will probably identified some quick wins.  This always happens when people start seeing the process and the handoffs between each other.

Don’t be scared if the diagram becomes large with 20+ activities. Later you can simplify by taking a group of activity boxes and “sending them to child” which means taking them and creating a lower level diagram.

Sometimes, where the process is well understood but not documented, this is really quick to do. In other cases, documenting the process highlights the fact that there is some disagreement how the process works (or should work) – and it takes a slightly longer.

But don’t underestimate the value of this mapping. We’ve got years of experience process mapping. Getting everyone on the same page – literally – is so empowering.

 Step 2. WHAT

You will go through the process diagram process step by step and ask the question “What in Salesforce do we use to deliver this step?”

To make the link you add an Org Model node to a process step. You find the node in the Org Model. This could be an object, field, page layout, email template, process builder workflow etc etc.  All the metadata in your Org – both core and managed packages – is in the Org Model tree structure.

In the right panel in the DOCUMENTATION tab click on “Copy node link”. Alternatively right mouse click on the node in the tree and select “Copy node link”.  This will save the node in the clipboard. Then go to the process step and right mouse click and select “Add links” and “Org Model Node”.

When you roll over the link a window will popup showing the linked process diagram.

Don’t be surprised when you find the same nodes are linked to a number of different process steps and are used by different departments. This is where the Org Model becomes a critical resource for impact analysis for any new changes.

There is no “right and wrong” here, but decide on an approach and be consistent to help people leverage this. For example, many people link the highest levels of their process map to the Objects involved. e.g. the top level box with “Issue to Resolution” or “Resolve Customer Issue” is linked to Case object, but also, Account, contact, perhaps Opportunity and maybe some custom objects that support the process.

Then at the detailed level, individual steps may have links to validation rules, specific triggers, or a detailed automated activity that was created in Process builder or Flow. The details of “Why” that process builder was built in the way that it was may not be best described in a process step – hence step 3…

Step 3. WHY

For each node that you link to a process step, you will then need to add the “Why” documentation. Often the most valuable documentation is the Why. What was the thinking behind the configuration and why was it configured in that way?

As you start linking items in the Org Model to the processes, look for anything that was created that describes why changes were made and what was updated: requirements, user stories, process sketches, ERD/data models, videos, specifications, screenshots, wire diagrams, photos of whiteboards, notes, audio clips from the developer.

The mantra is “if you created it, link it”.

We know this is hard, so we are thinking of ways to make it feel easier and more immediate. We’ve built a mobile app, so you can take a photo when you are in the meeting and post it straight to the item in the Org Model, dictate a note using Siri or add a URL link. Just like we all do with social media (The mobile app is in beta and going through Apple AppStore review).

Link types


Documentation can just be notes. You discovered something about how this item was configured or why and you want a place to record it. Quickly add a note, bearing in mind that a note is tied to a single item in the Org Model.

Documentation in cloud storage: 

This the evidence of why you made those changes to Salesforce; Specifications, notes, photos of whiteboards, screenshots, wireframes, data models/ERD, URL links to wikis, apps and files in cloud storage, wireframe designs…and the list goes on. Documentation can be stored anywhere – GoogleDrive, Box, Sharepoint, GitHub, wikis, webpages. The links can be stored in our central URL Links Library to make it easier to use any URL link to multiple places. And if the URL destination moves, you only have one place to change it – in the library. Everywhere that references it is immediately up-to-date. This is really important if you are linking to screens in Salesforce and you are moved from one instance to another i.e. NA32 to NA69 or you implement MyDomain and then rebrand.


Add a screenshot or photo of a whiteboard.  These are compressed and stored against a Org Model item.  If you want to link to multiple items either save in cloud storage and use URL link (above) or just attach multiple places.

Metadata on metadata; 

Data tables are an extremely powerful feature. You can use them to add custom fields to any item in a Org Model and then report on the data. When you set up a data table, you define how you want the data to be entered. You add the data table form to the Org Model item and then you can capture data. You have control of the types of fields: free text, checkboxes, picklists, nested lists. You can even say which are mandatory to be filled in and which are optional.

For example: you want to capture which fields in objects are used in integrations with 3rd party systems. We have created a Data Table called “Salesforce Integrations”. There is another called “Salesforce Lightning Migration” where you can track the migration of any item. BTW, you can link a data table to any item in a Org Model (and also processes steps, requirements & user stories).

Data models/ERD

Ideally, the data models are drawn in Elements, then you can link them just like you linked process steps. But they could also be PDFs of Visio, Powerpoint, Draw.io, Lucidchart or photos of whiteboards stored in cloud storage. It doesn’t matter what the format is. What does matter is that the diagrams were drawn because a data model is arguably the FIRST thing you should be doing before you jump into customizing Salesforce.


Adding tags means you can report on items later, filter and sort. Tags could be “Release36” and could also be “delete” or “reviewed”. If you use tags to identify which items are used by departments you can use them to identify training needs. Tagging will also help you understand the conflicts in changes to any item. You can then report on items by tag and filter, sort and group on any column.

And any report can be exported to XLS. So, you can use this as dynamic release notes highlighting everything that will be changed in a release, and which parts of your organization are going to be impacted.


Reports are launched from the icon on the right of the top toolbar, just to the right of the super helpful search. You can export the entire Org Model tree structure into an XLS via a report.


1.    How many levels down the process diagram hierarchy can you go?

A.  1

B.  5

C.  As many as you want

2.   What diagrams can you draw using the process mapping?

A.  Operational processes

B.  Data models

C.  Screen layouts

3.   Why are you linking process steps to nodes in the Org Model?

A.  To highlight how complex the process is

B.  To show the different processes that use a Salesforce configuration item and reduce conflicts

C.  To build Process Builder Workflows

4.   The documentation (notes, URL links, images) and comments you add to an Org Model node:

A.  Is stored until the Sandbox Org is deployed to Production

B.  Only documents that are in Salesforce Files

C.  Is linked automatically to the same node in every Org (Sandbox and Production) no matter which Org they were added in

5.   Tagging should be used:

A.  Because it is cool – who doesn’t like a #hashtag

B.  To be able to categorize and report on nodes

C.  When using a Data Table is overkill



NEXT – Unit 3 : HOW: Mapping your processes (30 mins)