Recently, I started thinking about how well I am caring for my Company’s Salesforce instance and what areas need improvement. There was one thing that stuck out like a sore thumb. Documentation. I realized that all of my hard work could be washed away by someone else because there is no reference of how to manage the tool. It is kind of like leaving your child with a babysitter without any instructions, or who to call in the case of an emergency. Love it or hate it, documentation is necessary.

Getting Started

Building good documentation will take some time so let’s do it right the first time! Here are a few things to consider when building your system content.

  • Be clear and concise. You should be able to hand the document to anyone outside of your organization, and they should be able to successfully read, understand and execute what you have documented.
  • Keep it Updated. Once the documentation is created, it still needs to breathe. Just like your Salesforce instance, this document will change. Don’t push this task to the back burner or you will end up having to rewrite everything.
  • Keep it Simple! Go to the level of detail you believe to be necessary for your organization and processes, but create extra work for yourself. Find supporting documentation from Salesforce and include the documents or URLs as part of your documentation. No need to reinvent the wheel!
  • Start with business critical processes. Write an outline or list of the processes that require documentation and prioritize them. Begin your documentation with the most critical processes and move down the list.

Choose a Repository

There are so many tools available to track documentation that one could go crazy looking for the perfect solution. Start by asking what others in your organization are using. More than likely, there is an existing tool that is being used to track documentation for company projects or IT related systems. My organization uses Confluence by Atlassian to document processes. Every employee has a license to the application which makes it the perfect location to document critical business processes.

Confluence is an easy WIKI style tool so you can easily build interlinking pages with a table of contents and share it with the organization, or just those employees who need to have access. In my opinion, WIKI style documentation tools are the way to go.

Whatever you choose, be sure that the individuals that need to access the information can.

What to Document

Administrator’s Handbook

This is where I start with every existing organization. The Administrator’s Handbook documents all of the critical business processes that an Administrator would need to know to keep the org up and running. This would include things like usernames and passwords to critical applications or integrations (protected from prying eyes of course); monthly processes which need to be manually managed on a regular cadence; contact information for any internal and external key contacts etc.

Honestly, this is the most important information and is now the only type of documentation I manage for my organization. Don’t burden yourself with over the top documentation. If you have the nuts and bolts documented, the rest will fall into order.

System Description Fields

I was recently going through a field by field analysis with one of my departments to review all of their page layouts and determine which fields need to go, and which ones need to stay. On several occasions, the question was asked: “What is the purpose of that field?” Unfortunately, I didn’t have an answer. The description field should be used to document the story or purpose behind every field.

In some cases, this may seem redundant as the field label adequately describes the purpose, but for the sake of clarity, expand on the usage with the description field. Make it a habit of providing these details every time a new field is created or modified.

Configuration Workbook

For large organizations that leverage multiple record types, configurations, and field values become difficult to manage, but a configuration workbook can help. My org has 16 different account record types, and each record type has a different set of fields and field values.

Managing the configuration can be a challenge sometimes, but the configuration workbook helps me to quickly and easily understand the layouts. If you don’t have an existing workbook, start by installing CloudConverter by Model Metrics. It compiles all of the metadata in your org, and allows you to export the details to Excel! The install is super easy, and the program works seamlessly!

Update: CloudConverter is no longer available. Some alternatives include a free AppExchange package called Octopus, and a Heroku based tool called Salesforce Toolkit. Both work well, but will require a bit of tweaking to get the data into a format I prefer. Also, check out the free Chrome Extension called CopyColumn which has proven to be helpful.

For smaller organizations, a configuration workbook isn’t necessary. Because the documentation lives in a static document (Excel), it can get out of date very quickly. Don’t freak out. This is not a document I use on a regular basis.

I have found it most helpful during a project where new fields, page layouts, and record types will be used. It creates order out of potentially confusing details and will make the configuration and implementation process easier. Once the project is done, store it with your other project documentation and don’t worry about updating it.

Click here to download an Excel copy of my configuration workbook template.

Is there specific documentation that you leverage in your org that works well for you? How has having your system documented helped with enhancements and new configuration or the fixing of problems? Sound off below by leaving a comment, and don’t forget to share!

Additional Reading:

Creating a Change Management Process: Part 1
Creating a Change Management Process: Part 2

Published by Brent Downey

Passionate about Jesus, being a dad, and Salesforce!

40 thoughts on “ How to Document Your Salesforce Instance ”

  2. In a past job we had a wiki that we updated with workflow diagrams, field definitions, and SOPs for frequent processes (exporting data, adding users, etc.)
    It was in constant flux with revision history.
    The one piece we really struggled with, however, was documenting the “why”. Why was this decision made? What trade-offs were considered? We never did figure that part out.

    Like

    Reply

    1. A wiki is a great idea! Central location, editable, and easy to manage! Great suggestion! I would agree that the “why” is an important piece to document as well, but much more abstract!

      Like

      Reply

  3. Great post, Brent, and great timing too. I’m looking forward to reading everyone’s responses, as I’m in the process of documenting everything here.

    Like

    Reply

  4. Great post Brent. And excellent comments too. For some time I’ve been using OneNote as my documentation repository for several client instances. Benefits include pastes that also paste the URL, and those screen shot pastes allow for field text searching! But I will compare this to a wiki; no doubt the wiki share capability is a huge benefit.

    Like

    Reply

    1. OneNote is a great tool. I use it a lot for capturing requirements and notes during meetings and I have found it fantastically useful! The downside is that it isn’t easily accessible to others on your team unless the workbook is shared!

      Like

      Reply

  5. Thanks for the template Brent – a huge help for getting me organized for my ETL. I started a wiki here too as it seemed like most of the information required to run this place is in people’s heads only. We play the lottery every week so we need a plan for when we hit the big jackpot!

    Like

    Reply

  6. Hi Brent, Thanks for the great post! We need to create a configuration workbook for which i am trying to use your template. I am relatively new to Salesforce, can you help me understand what the multiple columns with “Record Type Name” and “Record Type Notes” are used for (As far as i am aware record types help control page layouts and picklist values). The sample Leads sheet with the record type columns is confusing for me. Also, what is the significance of Record Type Name and Record Type comments in sheets such as Workflow Rules etc.

    Like

    Reply

    1. Hello Ganesh! The column titled Record Type Notes is where I list the field values for that particular record type. As an example, this would be the picklist values available for that record type. You would replace the columns titled Record Type Name with the name of your own record types then indicate which fields and field values are available for that record type down the column. This applies to all columns – including those on the Workflow sheet.

      Replace Record Type Name with the actual name of your orgs record type. I hope that helps!

      Like

      Reply

  7. Fabulous Post, thanks Brent. I also love Confluence and use it for all my Client’s Salesforce projects. I have a Confluence site where I am sharing all my Salesforce Knowledge (just things that I need to remember, so hopefully others will get use out of it too).

    Like

    Reply

  8. Dear Brent,
    Thank you for sharing such important information.
    I´m new at Salesforce and I´ve been asked to develop a specific method to document projects withing all the parts of the org. Basically how the configuration is set in order for an outsider of the project can get involve in a short period of time without wasting too much time going through all the formal documents of the project.
    Any advise on this subject?

    Best Regards,

    Sergio.

    Like

    Reply

    1. I would probably use a spreadsheet if you’re looking to capture metadata information (like fields, field level security, and so on). Create a tab per object or feature (i.e.: Workflows) and document as needed. The hard part with this type of documentation is that it takes a lot of work to keep it up-to-date. But, I know that some Admins really prefer to track configuration at this level.

      Like

      Reply

      1. Thank you for your response Brent!

        I´ve been reading about CWB(Config Workbook) & Org Comparator APP. And basically extracts the metadata of an org and displays it on a spreadsheet. This looks like a good option when the project is done.
        Another option is recording the computer screen while an admin navigates through the org to have a visual look of it.

        Like

        Reply

  9. Hi Brent, the link which goes to your excel template does not work 😦 Would you be able to direct me to it please?

    Thanks!

    Like

    Reply

  10. Great article Brent! I’m new to my current org and it has been pretty hard getting off the ground without any technical documentation – I’ve had a lot of mystery fields too that appear not to be used so am keen to use your config workbook!

    I’ve just had a look at the CloudConverter link and the recent reviews make it look like it doesn’t function properly anymore, are you still able to get it to work or have you found an alternative?

    Thanks!

    Like

    Reply

    1. Hi Rachel! I actually noticed that the link was broken over the weekend but hadn’t updated the post yet. I just added some new resources – check out the post again. CloudConverter is no longer available at all, but there are some good alternatives available.

      Like

      Reply

      1. That Salesforce Toolkit is amazing!!! Thank you so much for posting it! I caught your Admin Hero Salesforce webinar the other day and it was great, thank you so much for all of your great advice!

        Like

        Reply

  11. Brent, the link to your config workbook doesn’t work. Can you post an updated link? Always looking for the best version to use, yours sounds great!

    Like

    Reply

  12. Hello

    Nice work Brent thanks for it

    Does someone use the app Octupus ( free version) for Documenting ?

    And if so…. could someone give some tips how i can use it in an sensless way ?

    or some other tips

    thanks

    regards john

    Like

    Reply

    1. Hello Yannick

      SpringTool has maxed out my API requests. Any idea how to disable existing requests or disable SpringTool access to salesforce?

      thanks
      Alex

      Like

      Reply

  14. Is there a template for the admin handbook? I’d like to get an idea of a solid structure, I’m tasked to start the documentation

    Like

    Reply

    1. It kind of depends on what your company uses and what is accessible to other users that may need access (like when you’re on vacation or if you leave the company). You could do something simple like a Google or Word Doc, or a wiki, or a site on your intranet. See what’s available and go from there!

      Like

      Reply

  16. Great article – thanks – especially for the template. circumstances has landed me with the Admin role in our Not-for-profit and am going through a very steep learning curve. Documentation is one are I need to get my heard around. So thank you for your helpful article.

    Like

    Reply

  17. First of: thank you Brent for a great Blog. You do great work here 🙂
    So it might not be relevant for all you guys because the visual workflow aids in SFDC have gotten very good over the years, but I found yEd (https://www.yworks.com/products/yed) to be a great tool to start of documenting processes. In all companies that I have worked so far, this doesn’t exist anyway and it can help you create different maps: app architecture maps, business processes, etc.
    I hope this helps some of you.

    Like

    Reply
  19. Pingback: Saving Time With Change Sets – Admin Hero
  20. Pingback: 5 Horrible Habits You Need to Break Right Now – Admin Hero
  21. Pingback: Secrets Your Boss Never Told You About Salesforce Documentation | Brainiate Show

  22. Let me just dig up an old blog post! Any chance you have an updated link for the sample configuration workbook?

    Like

    Reply

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.