4. Org Documentation

 After completing this unit, you’ll be able to:

  • Understanding why documentation matters
  • Discover a documentation approach that works
  • Why you should document NOW
  • Building great documentation habits


If you want to use Elements Catalyst for capturing requirements you will need to run a free 14 day trial.


The Salesforce platform is very powerful, and as Spiderman was told: “with great power comes great responsibility”.  With every release, your Org gets more powerful but also more complex.

With everything else you need to do, documenting your changes is probably low on your priority list. But it shouldn’t be. Taking time for documentation will actually make you time in the longer term and greatly reduce the time take to do impact analysis and the risk that changes will break your Org. But how do you convince others – your co-workers and executives?  And when you do have the mandate to spend time on documentation and clean up, what is the most effective approach?

Every change you make has a risk that it will break something in your Org.  The impact analysis of every change with an undocumented Org is a huge time suck. Or you simply do no analysis and just hope (by the way, hope is not a strategy).

I love the excitement of deleting a field and waiting for the screams

Said no-one…EVER

Being able to exploit the new Salesforce features and rapidly reengineer your processes to respond to market changes is the goal of every company. The most innovative and agile will win. But for most Admins, their undocumented Org – what developed would call technical debt – kills that agility.


Documentation is more than the list of what metadata you added in a new release in Salesforce. We need to add why we added it as this gives greater insight into how it is used. In the business analysis training course we showed you how to develop requirements, business process maps and user stories that explain why you made the changes.

The only reason for documentation is so when you come back to it in 6 days / 6 weeks / 6 months you can understand the impact of changing it. Here is a list of some of the documentation:

  • Requirements: The triaged and prioritized list of requirements and user stories. These are in sufficient detail that they are the basis of the testing. Writing great requirements is a key skill.
  • Business Process Maps: Ideally, this is where all business change starts and how it is described. These are the simple business process diagrams that show the end to end flow of work and how Salesforce can support it. This validates and generates the requirements and user stories.
  • Data Models / ERD: No org changes should be made without a clear understanding of the data model implications.Metadata Descriptions:At a minimum, if the metadata item has a description field – and not all do – then complete it.
  • Metadata Documentation: Ideally, every important metadata item has more documentation than the 1000 ch in the description field. Link these to the metadata items in the metadata dictionary so you can track business purpose, requests but also links to other supporting documentation such as requirements, user stories, business process steps, specifications, screenshots, notes, wireframes and videos.
  • Commenting Code: Good coding standards should include adding comments in Apex and automation workflow.
  • User help: his should also be considered documentation, and often the documentation on why the meta item what created can double up as end-user.


Why don’t we document?

  • No Time/Not a Priority: Documentation is a critical part of configuration, not an optional extra. The costs of poor documentation are very clear. Just read a few OrgConfessions. The IDC Explorer Future of Work survey data showed that 40% of development time is was dealing with ‘technical debt’. Add to that the time firefighting when you make a change that breaks the Org and all hell breaks loose. It is negligent to build a core business app like Salesforce without documentation. Christopher Marzilli, Salesforce Product Director, Platform Success in his presentation “Decluttering Your Org” presentation said, “Devote a percentage of each release to clean up (recommend 10-25%)”.
  • No Business Case: You need a catalyst. Is it maxed out fields on key objects? FNO confidence that changes can be made with breaking the Org? The strongest driver is migrating to Lightning as it forces you to clean up page layouts and evaluate manage packages. Ideally you redesign operational processes which is the basis of all Org documentation. Importantly the Lightning migration will have budget and executive support.

We just did a study of 500+ Salesforce customers who made the move to Lightning, and they saw an average 41% increase in productivity

Lightning Experience, Readiness Check Overview


The challenge we hear all the time, is “My Org is such a hot mess. I have no idea where to start”.  Look at the lifecycle of an object that you are struggling with. You probably have a very clear view of your top 3 items on your 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 for Accounts, Contacts and Opportunities.
  • Users are complaining about slow page loads and busy page layouts so we need to look at the Case Object and how to reduce the fields on the page layouts
  • We’ve reached field limits on the Lead Object so need to work out which we can delete
  • There are multiple process builder workflows that all seem to do the same thing on the Product object.

For the area you are focusing on, follow this simple 3 step process:

HOW: How does this part of the org/business work? Document this as a business process diagram.

WHAT: What did you change in Salesforce to support it? Link each step in the process diagram to the Salesforce metadata items in the Data Dictionary that are required to deliver that process step e.g. objects, fields, email templates, Apex classes, process builder workflows, validation rules.

WHY: Why were changes made and where is the documentation that describes why and how you changed Salesforce?  Add or link the documentation to the Salesforce metadata items in the Data Dictionary.

At the heart of this is the WHAT (Metadata Dictionary) which lists all the metadata items.  Attached to each metadata items are the HOW (process maps, data models) and the WHY (documentation and requirements).