Documentation Advice from the Awesome Admin Community

Let’s face it, whether you’re a new or seasoned admin, creating robust documentation is key to success! Not only does it help users and peers better understand business processes, it also helps YOU when you’re having a hard time remembering why or how you created something months ago.

Since most of us have our best tricks and tips for documenting our own work, a while back, we reached out to the #AwesomeAdmin community to crowdsource a few favorites.

?#AwesomeAdmins, let's put our brains together and share some #TuesdayTips!

What's the best documentation tip you've ever given or received?

— Salesforce Admins (@SalesforceAdmns) June 29, 2021

Many #AwesomeAdmins responded to the call. Two main themes we saw were “just get started” and “get specific.” Check out the advice below.

Get started

#AwesomeAdmin Mark Jones has received some simple, but solid, advice that has stuck with him — always keep documentation up to date and “start writing documentation.” It’s straightforward advice, but it’s true! The hardest part of documentation is just starting and maintaining!

It's a simple one for me … but it was "keep it up to date". Outdated documentation is a real pain point. And a cheeky second one I was given was "start writing documentation". For a number of admins starting writing documentation is a massive hurdle itself.

— Mark Jones (@ThisIsMarkJones) June 30, 2021

Joey Eisenzimmer warns of a fatal mistake a lot of us make: trying to go back to document! Save yourself the heartache and start every new project or process with a fresh documentation doc.

Document early and often from the start. Trying to go back can be surprisingly challenging down the road ??

— Joey Eisenzimmer (@JoeyEisenzimmer) June 30, 2021

Dan O’Leary shares with us another simple but crucial tip: Add the date your documentation was created as well as when it needs to be updated! Marking down the date you want to update the document will keep you accountable!

Make sure you add prominently:

1. The date the documentation was created
2. When it expires or will need to be reviewed

— Daniel O'Leary (@danieloleary) June 29, 2021

Not sure how to get started? Daniel Gorton breaks down all of his best tips for documentation and shares an awesome documentation presentation from MVP Michelle Hansen.

✅ Document throughout a project
✅ Keep audiences in mind
✅ Review & update as needed
✅ .@mehansen82 has a magnificent presentation full of tips (https://t.co/Gj1JFHvwtf)
✅ Check out Writing for Web Accessibility on .@trailhead #TrailheadGO
https://t.co/lrK4wxbAwB

— Daniel Gorton ☁️??? (@SFTrailblazer) June 30, 2021

Get specific

Beyond just starting and maintaining, we saw some helpful tips from the community on how to be as specific as possible in order to benefit from the documentation months or even years down the line.

Pip Wilford shares an insightful bit of advice: Don’t write documentation for you.

Write documentation as if you're not going to be there to help! As I'm about to move on from my role, I'm realising all the things I've changed/updated without explanation, because it was clear to me, but now I'm leaving no-one will know why! ?

— Pip Low (@_pip_low_) June 30, 2021

As I mentioned earlier, writing documentation is one of the greatest gifts you can give your future self. John Schneider shares his trick to understanding exactly where errors have occurred.

Give your Validation Rules a unique number or code and include that in the Error Message. So when you get the inevitable error message you know what went wrong.

— John Schneider (@sfJohn__c) June 29, 2021

If you’re spending the time to carefully document your work, include the details that will matter most to you! Michelle Hansen shares the things that she often includes in her documentation below.

Include any key reports, dashboards or automations a field is used in, why it exists, who requested it, and how it’s filled out of not by a user in the UI—automation? Synced to an external system? Other?

— ⚡️ ☁️ Michelle Hansen ☁️ ⚡️ (@mehansen82) June 29, 2021

It was fun to hear what the community had to say about documentation. We also wanted to offer some advice of our own. Here’s some advice from our Admin Evangelists on documentation.

Advice from the team

Mike Gerholdt, Senior Director, Admin Evangelism:

“Write everything in the third person. This way, you’re providing a narrative point of view and can easily explain the process, decisions, and key stakeholders that were involved. Doing documentation in the third person also helps you provide a neutral point of view. An example would be, ‘The custom field ‘favorite color’ was added at the request of Farhan, the Dir. of Customer Service, so that agents could quickly suggest an alternate product color when speaking with customers on a call. It was approved in the April 2021 COE meeting.’”

Jen Lee, Admin Evangelist:

“Everyone likes building things but no one really likes documenting things. But if you do it little by little as you go, it’s not as painful. I’ve always told people working in the org that description fields are there for a reason. Use them. For example, for custom fields, describe what the field is used for. Is the field populated by an upstream system and what is it? Does the data populate a downstream system? And don’t just repeat the field name — that does no one any good. For formula fields or validation rules, describe what it does so the person doesn’t need to interpret the syntax. For flows, describe where it’s invoked from — which Lightning page, which button, etc. — so it helps the admin backtrack when troubleshooting.

I also document for each user story I work on, the design solution, and all the related components I create or touch as I build. This helps when it’s time to deploy, knowledge transfer, or if future enhancements are needed — you have all the possible impacted components already identified. So, please spend the time to document. It’s important to the future you and those who come after you. I think we’ve all been there, where we’ve had to make a change to something existing and there’s no documentation. We don’t know why decisions were made the way they were or understand the dependencies, and we end up unintentionally making changes that break the current process.”

J. Steadman, Lead Admin Evangelist:

“Make sure that all of your flows include fault handling. Customize an email message to explain where the error happened so it’s easier to troubleshoot.”

Have any more awesome documentation advice for us? Be sure to share it on social using #AwesomeAdmin.

Resources

• Career Development Page