Documentation — Not Just for Dummies

Documentation is essential for day-to-day business practices, but creating it can be daunting. Writing instructions for processes is not something many enjoy, but using a step-by-step outline to create documentation will help you successfully create documentation that will be clear, engaging, and useful. 

At Arkus, we know that the right documentation can make or break a project's outcome. As we approach the milestone of having completed 2,000 projects as a team, we've learned a few things about how to create excellent documentation. Here are some of our top tips for improving writing and working with yours.

But Why? 

Why is documentation important? What are we using it for? We create documentation for all sorts of reasons — to track our work, capture steps for processes we need to follow in the future, create checklists, or teach someone how to do something. Capturing information in a place that can be transferable to others allows data sharing. It prevents tacit knowledge, also known as knowledge only a single person knows, and is difficult to share. Consider this — if you win the lottery and quit your job to move to the Caribbean, would someone know how to perform your daily/weekly duties? Or would they struggle to figure out how to upload the file to the right database or how to manipulate the excel file that needs to go to the executive director by Friday at 10 AM? 

Develop

When documenting a process, whether internal or external, think about what a brand-new person at your organization would need to know to be successful. They may not know the intricate steps of a process — what button to click, which reference file to use, or how a template should look. 

Gathering all the data points beforehand is essential so the documentation is concise and well-rounded. Before building your documentation, create an outline, mentally or written down, so you know how to structure the documentation. 

For example, when preparing to write this blog, I captured several ideas that I wanted to touch on, then put those ideas into categories that became the topic headers of this blog. Building a house is much easier when a blueprint is drawn up before the concrete is poured. 

Build-a-Doc

Now that you have a blueprint for your documentation, it's time to do the thing with the stuff —writing. When documenting processes, I like to create multiple types of documentation to accommodate different learning styles. Some people learn the best while reading, others want to see someone do it, and some need to hear it. 

To accommodate many different learning styles, create a variety of document formats. Build a written document, record a training video, and, if necessary, host a live session walking through the steps in the documentation. Having many different formats allows the receiver of the information to digest it in a form best tailored to their learning style and availability to receive it. 

As with all documentation, you want to be straight to the point. Use screenshots when walking through a process to show where to click, where a field can be found, or how a page should look. You can use a screen capture tool or something like ScribeHow, which allows you to create documentation automatically using your clicks as data points. Be sure to highlight and circle the important information as you build your document in addition to a written description. Limit the length of written steps. You will want to write out any specific values or URLs to be accessed so the reader can directly copy and paste as needed. When recording videos, speak clearly, and slowly, and make sure your space is free of background noise. 

For video recordings, I like to use screencast-o-matic. It allows you to record your screen and audio simultaneously, and most importantly, IT'S FREE! 

Lastly, review your documentation. Put it through a basic spell-check or grammar tool (I like Grammarly) to verify there aren't any spelling or grammar errors. Then, review it yourself again or have another person look it over to verify that the process is documented correctly. This goes for videos too! You don't want to publish documentation only to realize that a chunk of the process wasn't documented, and you must redo the entire thing. Reviewing the next day after completing an initial draft helps me find errors I may not have seen before. 

Organize — What's in a Name? 

Your documentation is well-developed, your screenshots are impeccable, and the writing is clear. The next step before publishing is to organize. This doesn't mean throwing your document in a folder, never to be found again. There are ways to prevent losing your documentation into the void that can be a file storage system.

First, a good naming convention. A file name should be concise but descriptive enough to know what you're looking at. It should include the topic (or department) it applies to, the subject, and the date. For example: 

• Sales - Sales Process for Student Products - June 2022
• The topic or department is Sales.
• The subject is Sales Process for Student Products.
• The date is June 2022. A date doesn't have to be the standard mm/dd/yyyy format; it can be whatever format works best for your system. 

1. Why not rely on the last modified date of the file upload? 
1. An editor can accidentally modify files while viewing, data can be changed over time, or the document could be moved from its location. The last modified date may not always reflect the actual date the file should be "assigned" to. 

The second way to organize is by organizing your filing system. I could write a whole blog post on different ways to organize your files, but I'll keep it short and sweet. Having a few sets of cascading folders helps keep files organized internally and externally. Start with the broadest topic and then increase in detail as you move inwards by folders. For example, your first folder could be titled "Sales." The next layer includes two folders titled "Product Descriptions" and "Annual Sales Data." The "Product Descriptions" folder contains several files relating to the company's products and service descriptions. The "Annual Sales Data" folder contains subfolders for each year (2022, 2021, 2020, etc.) that contain the sales data for that year. A simple example, and for some organizations, it may be okay to push all the annual sales data files into one folder without organizing. The less you organize your filing system in advance, the more time you (and others) spend looking for the files you need. 

Publish

Distributing documentation, whether it be to your internal team or to a group you're working with, is the last and most important step. You will need to put it in a location that is easily accessible to the audience of the documentation. If it's for external users (for example, the sales team), put it in their sales drive or a Salesforce Chatter group. Once you upload the file to its location, share a link to the file location rather than sharing a copy of the document. This prevents duplicate file versions from floating around and encourages recipients to use the preferred file location instead of email. Knowing the preferred file location will also train your recipients on where to look for future documentation. 

Where to Go Next With Documentation

You developed, built, organized, and published your document to its intended recipients. Congratulations, you did it! Now you can enjoy your beautiful documentation while others reap the benefit of your knowledge. 

Want to talk about documentation? Reach out to me in the Salesforce Trailblazer Community @Gwyn Cross.