Publishing a Production Knowledge-Base Article Safely

Publishing an article into a production knowledge base is not a copy-and-paste exercise. Once content goes live on a customer-facing help centre or an internal engineering wiki, it is consumed by support teams, automated chatbots, and search engines within minutes. A badly formatted heading, a broken internal link, or an unreviewed configuration snippet can generate support tickets, mislead customers, or expose internal infrastructure details. This tutorial walks through the full production-safe lifecycle for creating and publishing an article through a typical enterprise content pipeline: a headless CMS backed by Git, authenticated through Entra ID, deployed via CI/CD to AWS, with staged review gates and a documented rollback path. The workflow described here mirrors what you will encounter at most organisations that treat documentation as a governed production asset rather than a casual wiki page.

#Prerequisites and required permissions

Before you start, confirm the following are in place. Do not attempt to shortcut these; missing access or context is the most common cause of stalled publishing requests, and requesting access mid-task typically adds a day or more of waiting on an approval workflow.

• An Entra ID account with the Content Contributor application role assigned in the CMS, provisioned through your team’s access request in the identity governance portal, with the role visible under your account’s assigned enterprise applications.
• Local access to the content repository (typically a Git repository holding Markdown or MDX source files) with your SSH key or Entra ID-federated Git credentials configured, and confirmation that you can clone the repository and push a branch before you begin drafting.
• A ticket reference in the change management system (for example, a ServiceNow or Jira change record) if the article documents a production process, API, or customer-facing feature. Note the ticket number before you create your branch, since it is used in the branch name and later in the change record.
• Basic familiarity with Markdown authoring and Git branching, since almost every production content pipeline treats articles as code, including pull requests, automated linting, and merge protections on the production branch.
• Read access to the CMS schema documentation, so you know which front-matter fields are mandatory before you open a pull request rather than discovering them from a failed build.

#How the publishing pipeline is structured

Most mature organisations, including KBY Technologies, do not allow direct edits to a live knowledge base. Instead, content moves through the same promotion path as application code: a draft branch, a pull request with mandatory reviewers, an automated build to a staging environment, a manual or automated approval gate, and a deployment to production via CI/CD. The CMS itself may present a friendly editing interface, but underneath it commits changes to a Git repository, triggers a pipeline build, and publishes static or server-rendered pages to a content delivery network fronted by AWS CloudFront, with origin storage in S3 or a headless CMS API. Understanding this underlying mechanism matters because when something goes wrong, you will be debugging a pipeline, not a text box, and knowing which stage failed shortens diagnosis considerably.

#Access and least-privilege considerations

Content platforms are frequently over-provisioned because teams default to giving writers full administrative access rather than scoping roles correctly. Before requesting access, identify the minimum role that lets you complete your task. The table below summarises the standard role tiers used in a typical enterprise CMS integrated with Entra ID.

As a new contributor, you should only ever request Content Contributor access. If you find yourself needing publish rights to get work done, that is a sign the review process is being bypassed, and you should raise it with your lead rather than requesting elevated access informally. Any request for a role beyond Content Contributor should go through the same identity governance approval flow as any other privileged access request, including a documented business justification and, in most organisations, a time-bound expiry rather than a permanent grant.

#Step 1: Create the draft in a feature branch

Clone the documentation repository and create a feature branch named according to your team’s convention, typically docs/<ticket-id>-short-description. Working in a branch, rather than editing directly in the CMS’s shared draft space, ensures your changes are isolated, reviewable, and revertible independently of anyone else’s in-progress work. Create the new article file inside the correct content directory; placing it in the wrong collection will cause the build pipeline to route it to the wrong navigation section or, in some CMS configurations, cause the build to fail entirely due to schema validation. Before writing anything, run the repository’s local build or lint command if one is provided, so you know the baseline is clean before you introduce changes.

Run the repository checks from the branch you intend to submit. Replace the example change identifier and slug with values from the approved ticket; do not copy the example branch name unchanged.

1git status --short
2git switch -c docs/CHG-1234-knowledge-base-update
3npm ci
4npm run lint

If the repository uses a different package manager or validation script, use the commands declared in its contributor documentation. The requirement is a clean local baseline and a repeatable validation result, not these specific npm commands.

#Step 2: Add metadata before writing body content

Every production article requires a metadata front-matter block: title, slug, owner, last-reviewed date, audience tag, and a classification flag indicating whether the content is public, partner-facing, or internal-only. Populate this before writing the body. Automated build validation in most pipelines will reject a pull request if required metadata fields are missing, and you will save yourself a failed CI run by completing this first. Pay particular attention to the classification flag: publishing an internal-only article without that flag set correctly is one of the most common causes of accidental external exposure of sensitive process detail. Where the CMS supports it, also set a review-due date at this stage rather than leaving it for later, since articles without a scheduled review date are the ones most likely to go stale unnoticed.

#Step 3: Write structured, verifiable content

Use consistent heading levels, starting at H2 within the body since the CMS template typically renders the article title as H1 automatically. Include working code samples only after testing them in a sandbox environment; never paste commands directly from a production incident without sanitising credentials, internal hostnames, or account identifiers. If the article references an API or configuration setting, link to the authoritative source rather than duplicating values that will drift out of date. Add a short summary paragraph immediately after the title so that search indexing and AI-assisted support tools can extract an accurate synopsis. Keep tables and code blocks small enough to render correctly on mobile-width help centre layouts, and avoid embedding screenshots of terminal output where a copyable code block would serve the reader better and remain accurate for longer.

#Step 4: Open a pull request and route it for review

Push your branch and open a pull request against the staging branch, not directly against production. Tag at least one technical reviewer with subject-matter authority and, if the content touches a regulated area such as data handling or customer authentication, tag a compliance reviewer as required by your organisation’s documentation policy. The review is not a formality: reviewers are checking for technical accuracy, correct classification, broken links, and whether the article duplicates or contradicts existing published content. Expect at least one round of requested changes on your first few contributions; this is normal and is the review process working as intended, not a sign you did something wrong. Respond to every review comment explicitly, either with a change or a stated reason for leaving the content as written, rather than resolving comments silently.

#Step 5: Validate in the staging environment

Once the pull request is approved and merged to the staging branch, the CI/CD pipeline builds and deploys the article to a staging URL, typically fronted by its own CloudFront distribution or a preview deployment slot. Before requesting promotion to production, verify the following on staging and capture evidence of each check, since this evidence is what you will attach to the change record in the next step.

1. The article renders correctly with no broken formatting, missing images, or malformed tables.
2. All internal and external links resolve, including cross-references to other knowledge-base articles.
3. The article appears in the correct navigation category and is discoverable through the staging site’s search function.
4. Any embedded code samples execute as documented when tested against a non-production system.
5. Metadata renders correctly in the page head, particularly the classification and audience tags, since these often drive access control on the front end.

A screenshot of the rendered staging page, a note of the search query used to confirm discoverability, and confirmation that link-checking tooling returned zero errors are usually sufficient evidence. Keep these artefacts with the pull request or the change record rather than relying on memory when asked later what was checked.

#Step 6: Raise the change record and obtain publish approval

For anything beyond a trivial typo fix, raise a change record referencing the pull request, the staging URL, the verification evidence gathered in Step 5, and a rollback plan. Attach the change record ID to the pull request description. The Release Approver reviews the change record, confirms staging validation was completed, and merges the staging branch into production. In organisations with a formal change advisory process, publishing a customer-facing article that describes a new feature or a changed process should be scheduled alongside the corresponding product or infrastructure change, not published independently ahead of the underlying capability going live. If your organisation observes change freeze windows around major releases or peak trading periods, check the freeze calendar before requesting approval, since even documentation changes can be deferred during a freeze if the platform team judges the risk of an unrelated build failure too high.

#Step 7: Publish and verify in production

After the merge to the production branch triggers the deployment pipeline, do not consider the task complete until you have verified the live result. Check the production URL directly, confirm the CloudFront cache has invalidated correctly if your platform requires a manual invalidation step, and search for the article through the live search index to confirm it has been crawled and indexed. If your organisation publishes through a CMS with an API layer, also verify that the article appears correctly through any downstream consumers, such as an internal support tool or an AI-assisted chatbot that ingests the knowledge base as a data source. Close out the change record only after this production verification is complete, noting the exact time the article went live and the URL you checked, so the record itself becomes useful evidence rather than an empty formality.

#Common failure modes

The table below lists issues graduate engineers most frequently encounter during their first few publishing cycles, along with the correct diagnostic action.

#Rollback procedure

Every publish action must have a corresponding rollback path defined before you request approval, not improvised afterwards. Because the content pipeline is Git-based, rollback is a version-control operation rather than a manual edit. If an article is found to be inaccurate, exposes sensitive detail, or breaks the production build after deployment, revert the merge commit on the production branch and allow the pipeline to redeploy the previous version automatically. Do not attempt to manually edit the live CMS record to undo a change, since this creates drift between the Git history and the deployed state, making future rollbacks unreliable. Confirm rollback success the same way you confirmed the original publish: check the live URL, confirm the CDN has served the reverted content, and close the change record with a note describing why the rollback was required. If the article was already indexed by search or ingested by a downstream chatbot, notify the platform team so cached copies can be refreshed rather than assuming the rollback alone clears every consumer’s cache. For a security-related exposure, such as an internal-only article briefly visible externally, treat the rollback as urgent, notify the platform administrator immediately rather than waiting for the standard change window, and record the exposure window explicitly in the incident note in case downstream systems need to purge cached copies.

#Monitoring and ongoing ownership

Publishing is not the end of the lifecycle. Assign an owner in the metadata who is responsible for reviewing the article at the organisation’s standard review interval, typically every six to twelve months, and set a calendar reminder or automated review-due flag if your CMS supports one. Many platforms surface analytics on article views, search click-through, and feedback ratings; review these periodically to identify articles that are generating support escalations rather than reducing them, which often indicates the content is unclear or has drifted out of date against the current product behaviour. Treat a spike in related support tickets shortly after publishing as a signal to re-open the article for review rather than assuming the content is correct simply because it passed the initial review gate.

#Closing summary

Creating a single article in a production knowledge base touches identity and access management, version control, automated build validation, staged verification, formal change approval, and a defined rollback path. None of these steps are optional formalities: each one exists because a real incident, somewhere, resulted from skipping it. As a graduate engineer, your goal on your first few publishing tasks is not speed but accuracy in following the process exactly as documented, so that reviewers and release approvers can trust your submissions without needing to re-verify every step themselves. Once you have completed a handful of articles through this full lifecycle, gathering staging evidence, raising a proper change record, and confirming production results before closing it out, you will find the pipeline becomes second nature. You will also start to recognise the same promotion, review, and rollback pattern in almost every other production change you make throughout your career, whether that change is a line of application code, an infrastructure configuration, or a piece of customer-facing documentation.