How to create and maintain useful documentation for you and your team

• Check for an existing source: Search AIR, SharePoint, and the relevant central UBC sites. Update or link to existing content before creating something new.
• Define the user need: Complete this sentence: “This page helps [audience] to [complete a task or make a decision].” If the purpose is unclear, the content is not ready to draft.
• Choose a drafting path: For short, low-risk content or updates, draft the content directly on an AIR page, preview it, and request a review if needed. For more complex, sensitive, or high-impact content or updates, co-author a Word file in SharePoint before publishing the approved content on AIR. Use SharePoint co-authoring and version history instead of emailing attachments back and forth. AIR revision history provides a similar safety net for published pages and posts.
• Ask the right people, not everyone: Involve the subject-matter expert, the accountable owner, and any other required reviewers and provide them with context, a clear deliverable, and a desired deadline.
• Assign maintenance before publishing: Record the owner, revision date, and review cadence,
• Publish one final version: Add the approved content to AIR and then link to it from other pages, messages, and onboarding materials.
• Retire the working copies: Archive drafts, label them clearly, or replace them with a link to the published source, so readers do not encounter competing versions.

• Define the purpose and audience: State who the documentation is for, what it helps them do, and the most important action they should take.
• Use a descriptive title: Prefer “Submit an expense reimbursement” over a broad title such as “Finance information.”
• Assign ownership: Identify the content owner, backup owner, and date the information was most recently reviewed or updated.
• Link, don’t duplicate: Link to the original policy, system, or central UBC resource instead of copying it. Add only the tailored context your Arts audience needs.
• Use standard paragraph formatting: Use one page title followed by short H2 sections and H3 subsections. Put steps in the order readers need them. Use numbered steps for a sequence and bullets when order does not matter.
• Keep paragraphs short: Focus on one main idea per paragraph and move scannable requirements, options, or key details into bullets.
• Write in plain language: Use familiar words, active voice, and direct instructions. Define acronyms the first time they appear.
• Make link text meaningful: Use descriptive calls to action instead of using “click here” or hyperlinking a full URL.
• Use screenshots sparingly: Include a screenshot only when the interface is difficult to explain in words. Crop it to the relevant area and plan to replace it when the interface changes.
• Design for accessibility: Use default headings and lists, descriptive links, alt text for all images, and instructions that do not depend on colour or icons alone.

✅ The page has a clear audience and user need and does not already exist

✅ The title clearly describes the task or topic

✅ The most important action appears near the top

✅ The content uses plain language and defines necessary acronyms

✅ The content uses headings, bulleted lists, and numbered steps so the page is easy to scan

✅ Central UBC resources are linked rather than copied

✅ Links use meaningful call-to-action text and open the correct, current destination (no broken links)

✅ Dates, contacts, roles, prerequisites, exceptions, and escalation paths are explicit where needed

✅ Images have appropriate alt text and are included only when they add value

✅ Permissions match the audience, and sensitive information is not exposed inappropriately

✅ The subject-matter owner, last updated date, and next review date are recorded in the content register

✅ Drafts and duplicate versions are archived, labelled, or replaced with a link to the published source

• Accountable owner: A unit manager or content lead sets priorities and approves major or high-risk changes.
• Responsible subject matter expert: The employee closest to the work keeps their assigned section accurate and initiates updates when the work changes.
• Consulted reviewers: Affected colleagues review only when their input is necessary.
• Informed audience: Employees affected by a significant change receive a short notice that links back to the published page.
• Site manager: One coordinator maintains the content register, sends review reminders, supports consistency, and initiates the annual cleanup (they are not the writer for every page).
• Backup owner (optional): Critical content has a named backup, so maintenance does not pause during leave or turnover.

• Immediately after a change: Critical procedures, access, privacy, or security guidance, and information affecting active services or deadlines.
• Each term or quarter: High-change, high-use, or time-sensitive content.
• Every six months: Operational guides that change periodically.
• Annually: Stable evergreen guides, ownership information, and lower-risk reference content.
• At a defined expiry date: Temporary announcements, pilots, event information, and transition guidance.

At each review, choose one action: keep, update, consolidate, or remove. Change the “last reviewed” date only after someone has actually verified the content.

Note: Removing content from a website is not necessarily the same as destroying a University record. Check the UBC Records Schedules before disposing of records.

• Add “create/update documentation” to project briefs, change checklists, and meeting agendas.
• Treat a change as complete only when the relevant guidance, links, owner, and review date are updated.
• End decision-making meetings by asking: What changed, who needs to know, and where will the decision be documented?
• When someone asks a repeated question, answer it and improve the published page at the same time.
• Reserve a small, recurring block of time for documentation debt instead of waiting for a large cleanup.
• Use the annual cleanup to address content that could not be fixed during normal work, not as the only time content is reviewed.

• Arts ISIT: Streamline your work with AIR and Microsoft 365: related guidance on using AIR as a central knowledge base and Microsoft 365 for collaboration.
• UBC Records Management: Understanding records management: UBC guidance on records, accessibility, retention, security and responsibilities.
• UBC Records Management: When to create a record?: UBC guidance on when activity in collaborative tools should be captured as a record.
• Nielsen Norman Group: Content Strategy 101: A content lifecycle model covering planning, creation, maintenance and unpublishing.
• Nielsen Norman Group: Intranet Usability Guidelines: Research-based guidance drawn from studies of 57 intranets.
• Microsoft Support: Document collaboration and co-authoring: Guidance for collaborative work in SharePoint and Microsoft 365.
• Microsoft Support: How versioning works in lists and libraries: Guidance for retaining, comparing, and restoring versions.
• UBC IT: Microsoft Copilot at UBC: Current UBC features, eligibility, security, and responsible-use guidance.
• Hollmann et al.: Ten simple rules on how to write a standard operating procedure: A peer-reviewed, practical guide to creating, reviewing, and maintaining procedures.