Pigment model documentation helps a finance team understand not only what a model does, but why it was designed that way and how to change it safely. Record the decisions, logic, data, ownership, and testing context that another administrator or planner will need after the original builders move on.

Get in touch to discuss your planning model

What should Pigment model documentation cover?

Useful documentation answers practical questions that arise during planning cycles: Where does this number come from? Which assumption can I change? What depends on this input? Who approves the result? How can I tell whether an update worked? A collection of screenshots or a feature inventory rarely answers those questions on its own.

Think of the documentation as a compact operating guide for the model. It should connect business intent to model structure and day-to-day processes. It does not need to repeat every configuration detail visible in the platform. Instead, capture context that is difficult to infer from the model itself, especially decisions, exceptions, and responsibilities.

This focus on maintainability complements choices made during Pigment model design. Design establishes a structure; documentation helps future owners preserve the reasoning behind it as the business changes.

Documentation is also a record of work, not just a presentation aid. That principle appears in technical studies beyond business systems, where documentation of work is treated as a distinct part of the process; see Scientific Studies of Pigments in Chinese Paintings for an example from pigment research. For a finance model, the relevant context is business purpose, assumptions, controls, and decisions rather than laboratory observations.

Which business decisions and scope should you record?

Start with the model's purpose and boundaries. State which decisions it supports, which teams use it, and which planning areas are included. For example, a finance model might support the operating forecast and scenario review, while a separate sales planning area owns quotas and territory-level assumptions. Be specific about what belongs in the model and what remains outside it.

• Business purpose: the decisions or planning outcomes the model supports.

• Scope: included entities, teams, planning areas, and time horizons, plus known exclusions.

• Users and audiences: who enters assumptions, reviews results, and consumes outputs.

• Planning cadence: when data is refreshed, submissions are due, and versions are reviewed.

• Key definitions: business terms such as bookings, headcount, or contribution margin, with the approved meaning used in the model.

Record meaningful scope changes as they happen. If a new business unit is added or a planning process moves into the model, note the date, reason, affected outputs, and accountable decision-maker. That history helps users distinguish an intentional change from an unexpected difference.

Also describe important boundaries between this model and adjacent processes. Identify which outputs are consumed elsewhere, who owns the receiving process, and whether users should treat a result as final or as an input for review. When a team adds a use case, these notes help it assess whether the existing scope still makes sense rather than expanding the model by default.

For organizations building a broader planning roadmap, connect the scope statement to the relevant planning use cases. This helps readers see whether the documented model supports finance only or is intended to connect revenue, workforce, operations, or other planning activities.

How should you document model structure and logic?

Describe the major components and how information moves between them. A simple map can identify source data, assumptions, calculations, review steps, and reporting outputs. Keep the description at a level that helps a new owner navigate; it should not become a second copy of the entire model.

For important calculations, explain the business rule in plain language, the inputs it depends on, and any exceptions. A formula may be inspectable in the system, but the rationale for a special treatment may not be obvious. Note why the rule exists, who approved it, and what downstream views or decisions could change if it is revised.

Where the model uses dimensions or shared structures, note their intended meaning and ownership. Explain which dimensions are common across planning areas and which are specific to a process. This is particularly useful when a new use case is added, because teams can see which existing structures should be reused and where a separate design is justified.

For more on the principles behind these decisions, see the guide to multi-dimensionality in planning models. Documentation should explain how the particular model applies those principles, rather than copy general design guidance.

A compact dependency register can make changes easier to evaluate. For each critical input or rule, list the model areas, reports, or planning decisions that rely on it. A finance leader reviewing a change can then see whether the impact is confined to one calculation or could affect a submitted forecast, a management view, or an adjacent planning process. Keep the register focused on dependencies that matter operationally; exhaustive lists that are difficult to maintain lose their value.

Include a short navigation guide for new owners. Identify the main pages or planning areas, the location of key inputs and outputs, and the path from source data to decision-ready report. If the model has several layers, explain which layer a user should inspect first when investigating a result.

What data, assumptions, and integrations need documentation?

For each significant data input, record its source system or source file, business owner, technical contact where applicable, refresh frequency, and the checks performed before planners rely on it. Note how missing, late, or corrected data is handled. If a process includes a manual adjustment, identify who may enter it and how it is reviewed.

• Data set or input name and the business purpose it serves.

• Source and expected refresh schedule, including dependencies or timing constraints.

• Role responsible for validating the data and resolving discrepancies.

• Important transformations, mapping assumptions, and known limitations.

• Fallback process when a refresh fails or the source is unavailable.

For assumptions, document the owner, unit, period, and approval process. An assumption register can distinguish centrally maintained values from planner-entered inputs. It can also record whether an assumption is a default, a target, or a scenario-specific choice. That distinction prevents users from treating every displayed value as an approved forecast.

Connected planning depends on clear handoffs between data and planning processes. The Pigment integrations guide provides broader context; for a specific model, add its own source-to-output map and operational contacts.

For each integration or recurring import, document the expected sequence: when the source is prepared, who initiates or monitors the transfer, what a successful refresh looks like, and how exceptions are escalated. A practical note might say that a planner should pause review if a designated source has not refreshed or if a reconciliation check fails. State the condition and next owner, not just the technical name of a connection.

Separate stable reference data from period-specific planning inputs where that distinction affects ownership. For example, a mapping maintained centrally may need a different review path from a forecast assumption entered by a business partner. Record how users request a correction, how it is approved, and whether the update applies retroactively. This makes data changes more traceable and reduces the chance that a one-off correction becomes an undocumented rule.

How should ownership, access, and workflow be captured?

Documentation should make responsibility explicit. Identify roles rather than relying on informal knowledge: model owner, process owner, data owner, administrator, reviewer, and final approver. A role can be assigned to a named person in a controlled internal directory, but the model guide should still explain the responsibility so a personnel change does not make it obsolete.

Describe the planning cycle as users experience it. Include submission deadlines, review stages, version or scenario conventions, and the conditions for reopening a period. Point out where decisions are made outside the model and how their outcomes are recorded. This gives users a process map rather than a list of technical components.

For access, document the principles behind role assignments, sensitive areas, and approval for changes. Avoid placing credentials or unnecessary personal information in a guide. A separate controlled record can hold detailed user assignments, while the general documentation explains how access is requested, reviewed, and removed. See Pigment access management for related implementation considerations.

A responsibility table can clarify handoffs without turning the guide into an organization chart. Describe who prepares, reviews, approves, and supports each recurring activity. Where a role is shared, identify the primary escalation point. Make it clear who can authorize a change to a business definition or planning rule, and who is responsible for checking the model after the approved change is made.

These responsibilities should align with the broader implementation and support approach around the model. When a partner, internal center of excellence, or managed service team participates, document the handoff between those groups instead of assuming everyone knows where one responsibility ends.

What testing and change history should be retained?

Record how the team checks that the model remains fit for use. Tests should reflect important business outcomes, not just whether a screen loads. Examples include reconciling a result to an agreed source, checking a known scenario, confirming that a changed assumption affects the expected outputs, and verifying that the correct people can complete a review step.

For each significant change, keep a short entry with the date, purpose, affected area, decision or approval, tests completed, and any follow-up required. The goal is not to create paperwork for every minor adjustment. Preserve enough history to explain changes that could alter reported results, planning responsibilities, or recurring processes.

• Write a test case in business terms, with expected behavior or reconciliation.

• Record who performed the test and when it was completed.

• Note the outcome, exceptions, and any unresolved issue.

• Link the test to the change or release it validates.

• Revisit recurring tests when scope, data sources, or logic changes.

Define where issues are logged, who triages them, and how a resolution is verified. That is especially valuable when the model is maintained by more than one administrator or when a support arrangement changes. A clear route for ongoing ownership also connects implementation decisions to Pigment managed services and support.

Make test evidence useful to the next reviewer. State the scenario or input used, the expected result, the actual result, and what the tester concluded. If the test depends on a source file or a particular planning version, identify it or point to its controlled location. When a check fails, record whether the change was corrected, deferred, or accepted with a documented limitation. This is more informative than a simple pass label with no context.

How can finance keep documentation current?

Make documentation part of the change process, not a one-time handover task. Assign an owner for each section and specify which changes require an update. A new source, a revised business definition, a changed approval step, or a material calculation update should trigger a review of the relevant entry.

1. Choose a home. Store the guide where authorized users can find it, with access and version history appropriate to its contents.

2. Use a consistent template. Keep sections predictable so owners can add or update information quickly.

3. Connect updates to decisions. Ask the person approving a material change to confirm that documentation and tests are updated.

4. Review before planning cycles. Confirm that owners, sources, deadlines, and key instructions are still accurate.

5. Test a handoff. Ask a new model user or administrator to complete a real task using the guide, then clarify gaps they encounter.

Keep the guide concise enough to maintain. A short index that points to detailed, controlled records is often more useful than a large document that duplicates every configuration. The right level of detail depends on model complexity, frequency of change, and how many teams rely on the outputs.

A useful maintenance routine assigns a specific trigger and reviewer. For example, a changed source mapping prompts the data owner to update the input notes; a revised approval path prompts the process owner to update the workflow section. During the pre-cycle review, check whether those edits were made and whether the instructions still match how users work. This is more reliable than asking a single administrator to reread the entire guide periodically.

Documentation also supports adoption. When users understand where to enter information and how reviews work, they are less dependent on informal explanations. Amvent's article on EPM change management discusses the wider people and process considerations that complement a reliable operating guide.

Before handing ownership to another person, run a practical handoff rather than relying only on a document review. Ask them to trace a key output to its source, explain an important assumption, find the owner of an issue, and identify the steps for testing a proposed change. Their questions expose missing context while the original owner is still available. Update the guide with answers that are likely to help the next person as well.

For finance leaders evaluating the operating model around a new platform, Amvent's Pigment guide for CFOs provides additional context on the questions finance leadership should ask.

Chat with us about model ownership

Frequently Asked Questions

Is Pigment model documentation the same as a user guide?

No. A user guide explains how to complete common tasks. Model documentation also records purpose, business logic, data dependencies, ownership, design decisions, testing, and change history. Teams may keep both, with clear links between them.

Who should own the documentation?

A designated model or process owner should be accountable for keeping it current, while data owners, administrators, and finance stakeholders contribute to their respective sections. Responsibility should be role-based so the process can continue when an individual changes roles.

How much detail should a team record?

Record enough context for another authorized person to operate the planning process, investigate a result, and assess a proposed change. Focus on business rationale, dependencies, exceptions, and controls that cannot be understood from the model alone. Avoid copying every visible configuration detail.

When should documentation be updated?

Update it when a material change affects the model's scope, data, logic, workflow, ownership, or controls. A periodic review before a planning cycle can catch outdated contacts and procedures, but it should complement updates made as changes are approved.

Make long-term ownership part of the model plan

Good documentation gives finance and planning teams a shared reference for how the model works and how it should evolve. Amvent Consulting is a Toronto-based boutique EPM consulting firm and official Pigment Delivery Partner. Its practitioner-led perspective includes experience leading a 250-plus-user Anaplan-to-Pigment migration as an end customer before founding the firm.

Get in touch to plan model ownership

Get in touch to review documentation needs

Get in touch with Amvent Consulting

A maintainable model is easier to hand over when its business purpose, operating rules, and accountable owners are visible and kept current.