Build the help into the system

Where documentation usually lives

In most companies, documentation for business systems is scattered or missing. There might be a training deck from launch, a shared drive with a few how-to documents, some recorded screen shares, and a lot of knowledge in the heads of two or three people.

Platforms like Salesforce have excellent help, but it documents Salesforce. It explains what a field type is or how a report builder works. It does not explain how your company qualifies a lead, what happens when a customer moves, or why a status means what it means.

Salesforce does have a Knowledge feature for writing your own internal and customer-facing articles. In my experience it is clunky, and I usually used third-party tools that worked better. Either way, the platform's help and your company's documentation end up as two separate things, in two separate places, and neither one knows which screen you are on. Often the company documentation never gets written at all.

The result is familiar. New staff learn by asking. The same questions come in again and again. When the person who knows leaves, the knowledge leaves with them.

What built-in help looks like

On a current client build, a telecom company running on a custom platform Opero built and runs, the help works like this:

• A help icon at the top of every page. Click it and the articles for that page appear. On the move-in screen, you see how move-ins work. On a property record, you see how properties, units, and residents relate.
• Search across everything. Anyone can look up a term, a process, or a screen.
• System and process together. Articles cover what the buttons do and also what the business expects: when to use this, who approves it, what happens next.
• Written with the system. Documentation was drafted as each part of the system was built, not as a project after launch.

Why it works now

For most of my career, documentation came after. We built the system, then wrote the documentation by hand. Every change after that carried an extra step: update the docs. It was slow, it competed with building features, and it fell behind.

AI changed that. Now I build the help articles at the same time as the system. The same AI coding tools that build a feature draft its help article from the code and the design that produced it, and the article ships with the feature. When something changes, its article changes in the same piece of work.

There is no documentation backlog, because documentation is never a separate task. That only works if it is part of the build from the start. Adding documentation to a finished system is a project. Writing it alongside the system is a habit.

What it changes

Faster onboarding. New staff can learn the system and the process from the system itself, on the page they are working on.

Fewer repeat questions. Many questions have an article to point to. When a question does not, that is a sign the article is missing, and it gets written.

Easier handover. A custom system's biggest risk is depending on the person who built it. Built-in help, along with the code and architecture documentation the client owns, means a new administrator or provider can understand what each part does and why.

Process clarity. Writing down how a process works often exposes that people do it three different ways. Settling that is worth doing anyway.

Part of a pattern

Built-in help is one of three ideas I now build into every system:

1. Help built in. The system explains itself.
2. AI as the admin interface. Changes are described, not clicked through setup screens.
3. The request queue inside the system. One place to ask questions and raise ideas, one ordered list of what happens next, and a record the company owns.

Together they make a system that explains itself, improves in the open, and does not depend on anyone's memory, including mine.

Where Opero fits

Opero designs, builds, and operates custom business systems, with help, documentation, and the request queue built in from the start. See custom CRM development, or start with a free review.