Creating Internal Documentation in Salesforce that Your Staff Will Actually Use
- Ohana Focus Team
- Jan 15
- 6 min read
By Ohana Focus | January 18, 2025 | 16 min read
Every nonprofit creates Salesforce documentation. Most of it sits in Google Docs folders, unopened. Staff ask the same questions repeatedly because finding answers takes longer than asking. The problem isn't lazy users—it's documentation designed for archives, not for action. Learn how to create guides, workflows, and help resources that staff actually reference: embedded where they work, written in their language, focused on their tasks.
It's time to learn some ways to create documentation that gets used, not because you force staff to read it, but because it's easier to use than to ignore.
Why Most Salesforce Documentation Fails
Before creating documentation, understand why previous attempts failed. The patterns are predictable:
It's Not Where Staff Are Working
Documentation lives in Google Drive or SharePoint. To access it, staff must remember it exists, remember where it's stored, open a new tab, navigate to the folder, find the right document, search within it, and context-switch back to Salesforce. This takes 3-5 minutes. Asking a colleague takes 30 seconds. Documentation loses.
It's Written for Training, Not Reference
Most documentation is structured like a textbook: comprehensive, sequential, concept-focused. Training documentation teaches concepts. Reference documentation answers 'how do I...?' questions. Staff need both, but they need reference documentation far more frequently.
System Language, Not User Language
Documentation uses Salesforce terminology without translating to an organizational context. System language is technically accurate but assumes users already understand WHY they're doing something. User language connects tasks to familiar organizational goals.
It Becomes Outdated Immediately
Someone creates documentation. Three months later, you add a new field. Six months later, you change a process. A year later, half the screenshots are outdated. Staff learn not to trust documentation.
The Four Types of Documentation You Actually Need
Instead of one comprehensive guide, create four focused documentation types:
Type 1: In-Context Help (Inside Salesforce)
What it is: Brief explanations that appear directly on screens where users work—field help text, page layout instructions, hover tooltips.
Best for: Answering immediate questions without leaving the page.
Examples:
• Help Text on 'Primary Campaign Source' field: 'Which fundraising appeal generated this gift? Used to measure ROI.'
• Rich Text on Opportunity page: 'Remember to check for duplicates before creating gifts.'
Type 2: Task-Based Quick Reference (Inside Salesforce)
What it is: Step-by-step instructions for specific tasks, organized by what users need to do.
Best for: Infrequent tasks staff perform correctly but not often enough to memorize.
Type 3: Process Workflows
What it is: Flowcharts and decision trees showing how organizational processes map to Salesforce actions.
Best for: Understanding multi-step processes with decision points.
Type 4: Conceptual Training Materials (External)
What it is: Comprehensive guides explaining concepts, philosophy, and why Salesforce is configured the way it is.
Best for: Onboarding new staff, major system changes, deep dives.
How to implement: Google Docs, wiki, or video tutorials. Can live outside Salesforce because they're consumed once or rarely.
Writing Documentation That Gets Used
Once you know where documentation lives and what types you need, focus on how you write it.
Start with Tasks, Not Concepts
Organize documentation around 'How to...' questions, not system objects. Task-centric organization maps to users' mental models.
Use Active Voice and Direct Instructions
Active voice with direct commands is faster to read and easier to follow.
Example: 'Enter the donor's name in Primary Contact. Enter the gift amount in Amount. Set Close Date to the date you received the gift.'
Include the Why, Not Just the How
Users follow instructions more reliably when they understand the overall purpose. When staff understand why a step matters, they're less likely to skip it.
Make It Scannable
Staff don't read documentation—they scan for answers. Help them:
• Use clear headers
• Numbered steps
• Bold key actions
• Use bullet points
• Add screenshots sparingly
Using Salesforce's Built-In Documentation Features
Salesforce provides multiple native tools for embedding documentation.
Field-Level Help Text
Every field can have help text that appears as a hover tooltip.
How to add: Setup → Object Manager → Select object → Fields → Edit field → Enter Help Text → Save
Best practices:
• Keep under 200 characters
• Explain what the field is used for, not just what it contains
• Give examples when helpful
Rich Text Components on Page Layouts
Add instructional text directly to page layouts where users enter data.
How to add: Setup → Object Manager → Page Layouts → Edit layout → Drag 'Rich Text Area' → Add content → Save
Custom Help & Training Tab
Create a searchable knowledge base inside Salesforce.
Benefits:
• Searchable within Salesforce
• Can include rich formatting, images, attachments
• Version control
Keeping Documentation Current
The best-written documentation is useless if it's outdated. Build maintenance into your workflow.
Make Documentation Part of Change Management
When you change a process or configuration, updating documentation is part of the implementation—not an afterthought. Documentation update happens BEFORE deployment, not after.
Assign Documentation Ownership
Someone must own keeping documentation current. Here are some options:
• Salesforce Admin: Technical documentation
• Process Owners: Development Director owns gift entry docs
• Hybrid Model: Admin maintains technical, departments maintain processes
Include 'Last Updated' Dates
Every documentation article should include 'Last Updated' date prominently. This helps users assess whether instructions are current.
Quarterly Documentation Audit
Schedule a recurring calendar reminder to review documentation:
• Assign a staff member to test each documented process
• Do instructions still work exactly as written?
• Have any fields or buttons changed?
• Update or archive outdated content
Measuring Documentation Effectiveness
How do you know if your documentation is working? Track its effectiveness using these indicators:
Decrease in Repeat Questions
If staff keep asking the database admin the same questions, the documentation isn't working. Track common questions over time. Decreasing frequency = documentation is being used.
User Feedback
Ask staff directly: 'When you had a question about [X], did you find the help text/guide useful?' Qualitative feedback reveals whether documentation is discoverable and understandable.
Knowledge Article Views
Salesforce Knowledge tracks article views. Review monthly: Which articles are viewed most? Which haven't been viewed in 6 months?
Time to Proficiency for New Hires
When new staff join, how long until they can perform routine tasks independently? Good documentation accelerates onboarding.
Common Documentation Mistakes to Avoid
One Giant Document
A 50-page 'Salesforce User Manual' is overwhelming and hard to maintain. Break into discrete, task-focused articles.
No Clear Entry Point
Staff don't know documentation exists or where to find it. Solution: Add a persistent 'Help & Training' tab.
Written for Experts, Not Beginners
Assumes users understand Salesforce terminology. Write for clarity, not brevity.
No Visual Hierarchy
Walls of text without headers, bullets, or numbers. Solution: Heavy use of formatting.
Documenting Everything
Focus on common tasks (80% of what users do). Rare scenarios can be handled by admin support.
Getting Started: Your First Documentation Project
Don't try to document everything at once. Start with the highest-impact opportunities:
Step 1: Identify Top 5 Frequently Asked Questions
Ask your database admin or review past support tickets: What questions come up repeatedly?
Step 2: Choose the Right Documentation Type
For each question, decide: Field help text? Rich text on page layout? Knowledge article?
Step 3: Write One Piece of Documentation
Start with the #1 most-asked question. Write it. Get feedback from 2-3 users. Revise. Publish.
Step 4: Measure Impact
Track whether the frequency of questions decreases. If yes, continue. If no, revise your approach.
Step 5: Build Incrementally
Add 2-3 pieces of documentation monthly. Within 6 months, you'll have covered most common scenarios.
Partner with Ohana Focus
Professional documentation services.
Ohana Focus helps nonprofits create Salesforce documentation that supports user adoption instead of sitting unused in file folders. We understand what makes documentation useful—because we've seen what makes it ignored.
Our documentation services include:
• Documentation audit
• Content strategy
• Writing and editing
• Salesforce configuration
• Style guide development
• Maintenance planning
• Staff training on maintaining documentation
Contact Information
Phone: (555) 123-4567
About Ohana Focus
Ohana Focus is a certified Salesforce consulting partner specializing in nonprofit implementations and user adoption. We've helped hundreds of organizations migrate to Salesforce, and we've seen the pattern repeatedly: Organizations invest heavily in training during implementation, then wonder why staff keep asking the same questions months later.
The problem is rarely the training—it's the lack of accessible, task-focused reference documentation that staff can consult when they need it. Training teaches concepts and builds confidence. Documentation supports daily work and enables independence.
Our approach to documentation prioritizes usability over completeness. We help organizations identify high-impact documentation opportunities, create content in users' language, embed documentation where staff actually work, and build sustainable maintenance processes so documentation stays current.
Topics: Salesforce Documentation, User Adoption, Knowledge Base, Training Materials, Help Resources, Best Practices, Nonprofit Cloud
Comments