How to Document Your Salesforce Instance

How_to_Document_Your_Salesforce_Instance-compressorRecently, 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

Load More Related Articles
Load More In How To

32 Comments


  1. Brad

    June 13, 2013 at 10:45 am

    Brent – good post. Would you be willing to share example versions of your Config Workbook and Admin Handbook?

    Reply

    • Brent Downey

      June 13, 2013 at 10:47 am

      I contemplated how to do this, but both are a work in progress. I will get a template put together for both and modify the post! Great idea!

      Reply

  2. Amber Neill Boaz (@amber9904)

    June 13, 2013 at 11:27 am

    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.

    Reply

    • Brent Downey

      June 13, 2013 at 11:30 am

      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!

      Reply

    • Brent Downey

      June 14, 2013 at 3:51 pm

      I have totally changed my direction and started a wiki yesterday! Thanks for the recommendation Amber! Such a great idea!

      Reply

  3. Kathy Chilcote

    June 14, 2013 at 10:02 am

    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.

    Reply

    • Brent Downey

      June 14, 2013 at 10:58 am

      Thanks Kathy! I actually found out yesterday that I can create a wiki type page via our intranet so I am in the process of moving/creating documentation there today!

      Reply

  4. Rob Kaplan

    June 17, 2013 at 12:19 pm

    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.

    Reply

    • Brent Downey

      July 19, 2013 at 10:31 am

      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!

      Reply

  5. jo

    July 9, 2013 at 12:44 pm

    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!

    Reply

    • Brent Downey

      July 19, 2013 at 10:32 am

      Send me a check for a couple hundred dollars when you win it big!

      Reply

      • jo

        July 19, 2013 at 10:33 am

        lol join the queue Brent 😉

        Reply

  6. Ganesh

    September 23, 2014 at 7:35 am

    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.

    Reply

    • Brent Downey

      September 23, 2014 at 8:05 am

      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!

      Reply

  7. Jodie Miners

    December 17, 2014 at 5:37 pm

    Fabulous Post, thanks Brent. I also love Confluence and use it for all my Client’s Salesforce projects. I have a Confluence site https://tdd.instawiki.com/ 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).

    Reply

    • Brent Downey

      December 18, 2014 at 1:56 pm

      Thanks Jodie! Confluence is a great tool for that.

      Reply

  8. Sergio peschiera

    November 23, 2015 at 7:35 am

    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.

    Reply

    • Brent Downey

      November 23, 2015 at 12:59 pm

      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.

      Reply

      • Sergio peschiera

        November 24, 2015 at 7:43 am

        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.

        Reply

  9. Mika

    February 1, 2016 at 3:49 am

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

    Thanks!

    Reply

  10. Rachel

    April 4, 2016 at 8:57 pm

    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!

    Reply

    • Brent Downey

      April 5, 2016 at 9:08 am

      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.

      Reply

      • Rachel

        April 5, 2016 at 3:57 pm

        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!

        Reply

  11. Laurie T

    October 21, 2016 at 11:09 am

    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!

    Reply

    • Brent Downey

      October 22, 2016 at 2:57 pm

      Hi Laurie! The link is working for me. Give it another try? It’s hosted on box.net – perhaps there is a restriction to that site from your office?

      Reply

  12. john

    November 2, 2016 at 6:15 am

    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

    Reply

  13. Yannick

    February 27, 2017 at 9:40 am

    Hello,

    I would suggest you to try a new tool, SpringTool, to generate your Configuration Workbook: https://springfive.com/springtool-offer/
    You can select the object you want to include and it will generate a nice spreadsheet with 1 object / tab including: field details, VR, Workflow, picklist LoV, etc
    This functionality is part of the Free license.

    Reply

    • Alex

      March 1, 2017 at 9:54 am

      Hello Yannick

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

      thanks
      Alex

      Reply

      • Brent Downey

        March 8, 2017 at 12:05 pm

        Hey Alex! You may want to contact Salesforce Support. I think they can help out and provide some insights. That or contact SpringTool support.

        Reply

  14. Jre2414

    April 6, 2017 at 11:02 am

    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

    Reply

    • Brent Downey

      April 29, 2017 at 10:51 am

      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!

      Reply

  15. salesforce implementation

    May 1, 2017 at 12:22 am

    Helpfull artilce!!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

Sponsors