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 By Brent Downey
Load More In How To

34
Leave a Reply

avatar
17 Comment threads
17 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
21 Comment authors
StefanGraemesalesforce implementationJre2414Alex Recent comment authors
  Subscribe  
newest oldest most voted
Notify of
Brad
Guest
Brad

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

Brent Downey
Guest

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!

Amber Neill Boaz (@amber9904)
Guest

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.

Brent Downey
Guest

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!

Brent Downey
Guest

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

Kathy Chilcote
Guest
Kathy Chilcote

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.

Brent Downey
Guest

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!

Rob Kaplan
Guest
Rob Kaplan

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.

Brent Downey
Guest

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!

jo
Guest
jo

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!

Brent Downey
Guest

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

jo
Guest
jo

lol join the queue Brent 😉

Ganesh
Guest
Ganesh

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.

Jodie Miners
Guest
Jodie Miners

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).

Sergio peschiera
Guest
Sergio peschiera

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.

Mika
Guest
Mika

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

Thanks!

Rachel
Guest
Rachel

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!

Laurie T
Guest
Laurie T

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!

john
Guest
john

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

Yannick
Guest

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.

Alex
Guest
Alex

Hello Yannick

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

thanks
Alex

Jre2414
Guest
Jre2414

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

salesforce implementation
Guest

Helpfull artilce!!

Graeme
Guest

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.

Stefan
Guest
Stefan

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.

Sponsors

Cirrus Insight

SUBSCRIBE ALREADY!

SUBSCRIBE ALREADY!

Join the bomb diggity Admin Hero email list and never miss a post. Like, never ever!

Hizza! You're subscribed! Nothing but good times ahead!