Documentation management - quick start guide

Documentation rots. Not dramatically, not all at once, but quietly: a screenshot from two releases ago, an AQL query referencing an attribute that was renamed, a "best practice" that stopped being best six months back. You only notice when a customer follows the guide and it breaks.

The Documentation Management schema treats your documentation as governed operational content. It gives you structured tracking for every page, every factual claim, every screenshot, and every review cycle. When something drifts from the truth, you catch it before your readers do.

Seven object types, 68 attributes, seven reference types. This guide walks you through deploying the schema, populating it, and putting it to work.

---

Before you begin

You need two things in place before you start:

• JSM LaunchPad installed with a Pro licence. Documentation Management ships as a standard-tier schema, but LaunchPad itself requires a Pro licence for schema deployment.
• Access to Assets in your workspace. You need Object Schema Manager or Jira Admin permissions to create and configure object schemas.

If you are not sure whether Assets is available, check Settings > Products > Assets in your Jira instance. If you do not see it, your Jira plan may not include Assets (it requires Jira Service Management Premium or Enterprise).

---

Deploy the schema

Deployment takes under a minute:

1. Open JSM LaunchPad from the Apps menu in your Jira navigation bar.
2. Select Documentation Management from the template gallery. It sits in the Governance category.
3. On the configuration screen, set the schema name and schema key. The default name ("Documentation Management") works for most teams; change it if you run multiple documentation schemas for different product lines. The schema key is the short prefix that appears at the start of every object key in Assets (e.g., DOCM-1, DOCM-2). You can set this to whatever makes sense for your organisation's naming conventions.
4. Toggle sample data on or off. Sample data gives you a handful of pre-populated objects to explore, which is useful if you want to see the schema in action before adding your own content. You can delete sample data later without affecting the schema structure.
5. Click Deploy.

LaunchPad creates everything for you: 7 object types, 7 reference types, all attributes pre-configured with the correct types and allowed values. If you enabled sample data, you will also see example objects linked together.

Screenshot: DeployFlow with Documentation Management template selected

---

Populate your Schema objects first

The Schema object type is your reference data layer. It answers the question: "Which LaunchPad schemas does our documentation cover?"

Create one Schema object for each LaunchPad schema your organisation uses. If you run Core, Standard CMDB, and SLA Management, you create three Schema objects. Every Document you track later links back to one of these.

What each attribute means

Attribute	Type	What to enter
Schema Key	Text	The short identifier for the schema (e.g., CORE, SCMDB, SLA). Use the same keys LaunchPad uses internally.
Version	Text	The schema version you have deployed (e.g., 1.1). Update this when you upgrade.
Tier	Select	Which licence tier the schema belongs to: Core, Paid, Enterprise, or Domain.
Category	Select	The functional category: Foundation, ITSM, Security, Operations, or Governance.
Object Type Count	Integer	How many object types the schema contains. Useful for quick reference when auditing coverage.
Status	Select	Active, Deprecated, or Draft. Set to Active for any schema you are currently running.

Example record

Create your first Schema object with these values:

• Name: Core Schema
• Schema Key: CORE
• Version: 1.1
• Tier: Core
• Category: Foundation
• Object Type Count: 7
• Status: Active

Repeat for each schema you use. These are slow-changing reference objects; you will only update them when you deploy a new schema or upgrade an existing one.

---

Create your first Document objects

This is where the real tracking begins. A Document object represents one documentation page (or one logical unit of content, if your pages are long enough to warrant splitting).

Pick an actual page from your documentation to use as your first record. Something important, something you know needs attention. Walk through each attribute:

Core identity attributes

Attribute	Type	Guidance
Section	Text	The docs section this page lives in (e.g., "Schemas", "Getting Started", "Integration").
Tier	Select	Public (visible to everyone) or Gated (requires authentication).
Doc Type	Select	Guide, Reference, Tutorial, Concept, FAQ, Release Note, or Schema Overview. Pick the one that best describes the page's purpose.
Complexity	Select	Beginner, Intermediate, or Advanced. This is the reader's required skill level, not a judgement on how well the page is written.
Owner	Text	The person or team responsible for keeping this page accurate.
Reviewer	Text	The person who reviews changes before publication. Can be the same as the owner for small teams.

The two-status model

Documentation Management tracks two independent status dimensions. This is the most important concept in the schema, so take a moment to understand it.

Editorial Status tracks where the page sits in the content lifecycle:

Value	Meaning
Draft	Being written or substantially rewritten
In Review	Content complete, awaiting peer review
Published	Live and available to readers
Archived	No longer current; kept for reference

Validation Status tracks how thoroughly the page has been checked against its source of truth:

Value	Meaning
Unchecked	Not yet validated
JSON Validated	Checked against production template JSON files
Capability Verified	Platform capability claims verified
AQL Verified	All AQL queries tested and confirmed working
Fully Validated	All validation types passed

A page can be "Published" editorially but "Unchecked" for validation. That is not a contradiction; it means the content is live but has not been formally verified against production data. The goal is to move every published page toward Fully Validated.

Remaining attributes

Attribute	Type	Guidance
Slug	Text	The URL path for this page (e.g., /docs/reference/core-schema/quick-start).
Product Version	Text	The LaunchPad version the page documents.
Doc Version	Text	The page's own version, using semver (e.g., 1.0.0).
Last Reviewed	Date	When the page was last formally reviewed.
Next Review Date	Date	When the next review is due.
Review Cadence	Select	Monthly, Quarterly, Biannual, Annual, or Ad Hoc.
Applies To Schema	Reference	Link to the Schema object created in the previous step. This is how you connect documentation to the schema it covers.
Word Count	Integer	The page's word count. Useful for estimating reading time and spotting pages that have grown unwieldy.
Reading Time	Text	Estimated reading time (e.g., "~8 min").
Status	Select	Active or Inactive. Set to Active for any page you are maintaining.

Set the Applies To Schema reference to link your new Document to the Schema object you created earlier. This is the first reference in the schema, and it is the one that ties everything together: every query about "which documents cover this schema" runs through this link.

Screenshot: Document object creation form showing both status fields

---

Record a Validation Run

You have a Document. Now check whether it is actually correct.

A Validation Run records the results of a single verification pass against a document. You might check a page against the production JSON to confirm object type names are right, or test every AQL query to make sure they still return results. Each check gets its own Validation Run.

Walk through

1. Create a new Validation Run object.
2. Set the Validation Type. Choose the type that matches what you are checking:
   • JSON Alignment: comparing the page against production template JSON files
   • AQL Verification: running every AQL query in the page and confirming results
   • Capability Check: verifying that platform capability claims are accurate
   • Platform Fact Check: confirming facts about Jira Service Management, Assets, or related products
   • Link Audit: checking that all links resolve correctly
   • Full Audit: a comprehensive pass covering all of the above
3. Describe the Scope. What specifically did you check? "All object type names and attribute counts" or "AQL queries in the deployment section" or "Every screenshot against current UI."
4. Record the Result: Pass, Fail, Partial, or Skipped. Be honest. Partial is not a failure; it means some things checked out and some did not.
5. Set the Severity. How serious are the findings? Critical (page is dangerously wrong), Major (significant errors), Minor (cosmetic or low-impact issues), or Info (observations, not errors).
6. Note the Source Of Truth. Where did you check against? The production JSON file path, a live Jira Service Management instance, the Atlassian documentation URL.
7. Record your Findings. Free text. Be specific: "Line 47: attribute 'Category' listed as 'Type' in the table" is useful. "Some errors found" is not.
8. Fill in Checked By and Date Checked.
9. Write the Remediation Summary. What needs to happen to fix the issues? This is the handover to whoever will make the corrections.
10. Set the Document reference to link this Validation Run to the Document you are validating.

After saving, the Document now has a linked Validation Run. You can update the Document's Validation Status to reflect the result (e.g., move from Unchecked to JSON Validated if the JSON alignment pass succeeded).

---

Track a Capability Claim

Every documentation page makes factual claims about what the platform can do. "AQL supports cross-schema references." "Automation rules can update Assets objects." "You can create up to 500 object types per schema." These are capability claims, and they are the most likely things to break silently when the platform changes.

Walk through

1. Find a factual claim in your documentation. Read through the page you registered as a Document and pick one specific claim about what Jira Service Management, Assets, or LaunchPad can or cannot do.
2. Create a new Capability Claim object.
3. Set the Claim Type:
   • Platform Capability: something the Atlassian platform provides natively
   • Product Capability: something LaunchPad specifically enables
   • Limitation: a documented constraint or restriction
   • Workaround: a non-obvious method to achieve something
   • Best Practice: a recommended approach
   • Implementation Detail: a specific configuration or setup step
4. Enter the Claim Text. Quote the claim exactly as it appears in the documentation, or paraphrase if the original is long.
5. Set the Platform: Assets, Jira Service Management Cloud, Jira Automation, Forge, Confluence, or Other.
6. Set the Verified status. New claims start as Unverified. After checking, move to Verified (confirmed accurate), Disputed (evidence suggests it is wrong), or Obsolete (no longer relevant).
7. Note the Verification Source. Where can someone confirm this claim? An Atlassian docs URL, a test instance, a support ticket reference.
8. Set the Risk Level: Critical (if wrong, causes data loss or security issues), High (causes broken workflows), Medium (causes confusion), or Low (cosmetic or minor).
9. Set the Document reference to link this claim to the page where it appears.

The verification workflow is straightforward: Unverified is the starting state. When someone checks the claim, it moves to Verified or Disputed. If the platform changes and the claim is no longer relevant, set it to Obsolete. Periodically review all Unverified and Verified claims to catch drift.

tip

Start with high-risk claims. A wrong claim about data deletion behaviour is more dangerous than a wrong claim about icon colours. Sort by Risk Level and work down.

---

Manage Media Assets

Screenshots and diagrams go stale even faster than text. A UI redesign, a renamed menu item, a moved button: suddenly your carefully annotated screenshot is teaching people to click something that no longer exists.

Walk through

1. Create a Media Asset object for each screenshot, diagram, GIF, video, or icon in your documentation.
2. Set the Asset Type: Screenshot, Diagram, GIF, Video, or Icon.
3. Set Screenshot Required. This boolean field marks whether a screenshot is needed at this position. Useful for tracking planned screenshots that have not been captured yet.
4. Set the Media Status:
   • Missing: the asset does not exist yet but should
   • Placeholder: a temporary or low-quality version is in place
   • Current: the asset is up to date and accurate
   • Outdated: the asset no longer matches the current UI or data
   • Not Applicable: no media is needed at this position
5. Enter the File Path where the asset is stored (or will be stored).
6. Enter the Source URL if the asset references an external resource.
7. Write the Alt Text. Descriptive alt text for accessibility. Describe what the image shows, not just what it is.
8. Note the Placement. Where in the document does this asset appear? "Below the deployment steps heading" or "After the AQL query table."
9. Set Last Updated to today's date.
10. Set the Document reference to link this asset to the page it belongs to.

The real power here is the Media Status field. Run a query for all Media Assets where Status is "Outdated" or "Missing" and you have an instant to-do list for your next screenshot session.

---

Set up Review Cycles

Documentation needs regular review, not just when someone spots a problem. The Review Cycle object type lets you schedule and track these reviews systematically.

Walk through

1. Create a Review Cycle object for a scheduled review of your Document.
2. Set the Review Type:
   • Scheduled: a regular, cadence-driven review (quarterly, biannual, etc.)
   • Ad Hoc: triggered by a specific concern or reader feedback
   • Release Triggered: prompted by a new product release that may affect the content
   • Audit Response: a review initiated in response to a validation failure or audit finding
3. Set the Scheduled Date. When is this review meant to happen?
4. Leave Completed Date blank until the review is done.
5. Enter the Reviewer. Who is responsible for conducting this review?
6. Leave Outcome blank until the review is complete. After review, set it to:
   • Approved: content is accurate, no changes needed
   • Changes Required: issues found, edits needed
   • Escalated: problems beyond the reviewer's authority to resolve
   • Deferred: review postponed (note the reason)
7. Add Notes with any context: what to focus on, known concerns, related issues.
8. Set the Document reference.

After completing the review, fill in the Completed Date, set the Outcome, and update the Notes with your findings. Then update the Document's Last Reviewed and Next Review Date attributes to keep the cycle moving.

tip

Match the Review Type to how the review was triggered. If your quarterly cadence prompted it, use Scheduled. If a new LaunchPad release prompted it, use Release Triggered. This gives you data on why reviews happen, which helps you tune your review cadence over time.

---

Configure Release Gates

Before publishing new or substantially updated documentation, you want to confirm it meets your quality bar. Release Gates are the checkpoints. Each gate represents one thing that needs to be true before the page goes live.

Walk through

1. Create a Release Gate object for each checkpoint your documentation must pass.
2. Set the Gate Type:
   • Content Complete: all sections written, no placeholder text remaining
   • Validation Passed: at least one Validation Run has passed for the document
   • Screenshots Current: all Media Assets linked to this document have a status of Current
   • Peer Reviewed: another team member has reviewed the content
   • Stakeholder Approved: a product owner or subject matter expert has signed off
3. Set the Gate Status: Not Started, In Progress, Passed, Failed, or Waived.
4. Set Blocking. This boolean determines whether this gate can prevent publication. Content Complete and Validation Passed are typically blocking. Stakeholder Approved might be non-blocking for minor updates.
5. Enter Required For Release. Which release or publication milestone does this gate belong to?
6. Leave Approved By and Date Completed blank until the gate is resolved.
7. Add Notes if needed (e.g., "Waived because screenshots depend on unreleased UI").
8. Set the Document reference.

Gate lifecycle

A gate moves through a predictable sequence:

Not Started (gate created, work has not begun) -> In Progress (someone is actively working on the checkpoint) -> Passed (checkpoint satisfied), Failed (checkpoint not met, needs remediation), or Waived (checkpoint deliberately skipped with justification).

Which gates should be blocking? That depends on your risk tolerance. A reasonable starting point:

Gate Type	Blocking?	Rationale
Content Complete	Yes	Publishing incomplete content harms trust
Validation Passed	Yes	Unvalidated content may contain factual errors
Screenshots Current	No	Outdated screenshots are bad, but not dangerous
Peer Reviewed	Yes	A second pair of eyes catches what the author missed
Stakeholder Approved	No	Useful for major releases, overkill for minor edits

Adjust these to match your team's maturity and risk appetite. The point is to make the decision explicit rather than leaving it to whatever feels right at publication time.

---

Suggested first actions

You have the schema deployed and you understand how each object type works. Here is what to do next, in priority order:

1. Create Schema objects for each LaunchPad schema you use. This is your reference data; everything else links back to it.
2. Create Document objects for your 10 most critical pages. Start with the pages that get the most traffic, cover the most complex topics, or have the highest risk of being wrong.
3. Run one Validation Run per document. Pick the validation type that matters most for each page. For schema documentation, start with JSON Alignment. For integration guides, start with Capability Check.
4. Identify high-risk Capability Claims. Scan your top 10 pages for factual assertions about platform behaviour. Create Capability Claim objects for anything rated Critical or High risk.
5. Audit your screenshots. Create Media Asset objects for every image in your top 10 pages. Set the Media Status honestly. You will likely find a mix of Current, Outdated, and Missing.
6. Set review cadences. Create a Review Cycle for each of your top 10 documents. Quarterly is a sensible default for most pages; monthly for pages that cover fast-changing features.
7. Configure release gates for your next publication. Before you publish your next documentation update, create gates and decide which are blocking. This one act turns "I think it is ready" into "I can prove it is ready."

---