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