Writing and Documentation

Guiding Principles

• If you are not sure where something should go, ask.
• Check for existing materials before you start writing/doing anything.
• Do not put generic things into client-specific places. Anything that needs to be specific can reference generic content rather than repeating it.
• The majority of things should be arranged around the feature. Try not to split things by:
  • Type of thing, for example meetings, specs, delivery guides
  • Service, for example QA, design, content ops, live ops
  • Client, for example NBA, WNBA
  • Department, for example delivery, sales
  • Status, for example in-progress, complete
• Unless there is a good reason to do so.

Creating Sections, Sub-Sections, and Pages

Sections

Create a new section in Confluence when you have a distinct, broad area of information or a project that merits its own categorised space. Examples:

• Product Development: Sections for each stage of product creation, including designs, timelines, and market insights.
• HR and Policies: Centralised section for onboarding, employee handbooks, and policy documents.
• Client Projects: Individual sections for each client, including plans, communications, and deliverables.
• Training Resources: Dedicated area for training modules, resources, and development plans.
• Goals and KPIs: Section tracking annual objectives, department goals, and performance reports.

Pages

A new page is warranted when you have specific information or documentation that needs to be shared and does not fit into existing pages, or needs its own space for clarity and focus.

Examples:

• Product Roadmap: New development phases or strategy changes.
• Project Post-Mortem: Lessons learned from major projects or events.
• Policy Updates: New legal, regulatory, or company policy updates.
• Onboarding Guide: New-hire integration guide to company culture and tools.
• Customer Feedback: Insights and reviews to inform product/service improvements.

Organising Your Content Effectively

Ensure sections, sub-sections, and pages are organised logically and intuitively to align with team needs and project objectives. Adopt consistent and descriptive naming conventions for page titles.

Typically this means:

• Alphabetical Ordering (A-Z): For easy navigation.
• Prioritise Pages: Within sections before sub-sections.
• Logical Exceptions: Important guides can be placed prominently.

Ensure Content Relevance

A common challenge with Confluence documentation is blending temporary content with long-term reference material. To address this, prioritise clear organisation, precise titling, and regular archiving/deletion.

Reference files provide long-term foundational information:

• Company policies and procedures
• Project documentation
• Training materials and onboarding guides
• Specifications

Temporary files are for short-term use:

• Draft documents under review
• Work-in-progress documents not yet finalised

Titles

All document titles should follow this structure and include the following where relevant:

• Shared: - Shared added as the final part of the title so we know it is shared externally
• Client: - Client added after the document title
• Section: Section Name if you need to scope something to its parent section
• Date: Date in dd/mm/yyyy format, used only if essential (Confluence has created/last-modified dates on each page)

Full structure (if all tags are used):

Section Name - Document Title - Date - Client - Shared

Do not include:

• Version numbers (version history is built in)
• Statuses (do not include Draft or WIP in titles)
• Hyphens and underscores for spaces
• Special characters

Page Contents

Clarity and Brevity

• Employ bullet points for step-by-step instructions to create clear, concise, and accessible documentation.

Avoid Jargon

• Use clear language and explain/avoid acronyms and specialised terms unless widely known.

Proofreading

• Ensure pages are free from errors, up to date, and relevant.
• Check spelling, grammar, link functionality, and alignment with current practices.

Acronyms Guidelines

• Spell out acronyms on first use within a section and avoid repetition.
• Do not use acronyms in titles unless widely known.
• Do not pluralise acronyms with an apostrophe.

Example: write "Application Programming Interface (API)" when first mentioned, then "API" thereafter.

Optimise Link Use

• Use concise paths for internal navigation and full URLs for external resources, avoiding excessive links.

Confidential or Restricted Access Links

• To securely link confidential content, clearly label it as "Restricted Access" and use backticks to make links non-clickable, requiring copy/paste.
• Include a note or contact for access permission, for example: "Contact IT for access."

Formatting Standards

• Maintain uniformity in font, style, and spacing to enhance readability.
• Headings should be used as headings (not manually bolded/underlined body text).
• Use a clear hierarchy starting at Heading 2 and working down.
• Do not add manual line breaks between sections/paragraphs.
• Do not number headings.

Minimise Incomplete Content

• Avoid publishing placeholders such as "TBD" or "To Follow" in visible docs.

Be Selective with Videos and GIFs

• Video and GIF content can quickly become outdated.
• Prefer detailed text instructions unless there is a strong reason for media.

Be Careful with Confluence Templates

• Avoid templates when they lead to incomplete or irrelevant content.
• Start with a blank page unless a template is clearly appropriate and will be cleaned up.
• If creating a true template page, use:

[TEMPLATE] Name of Page

Avoid Document Version or Revision Tables

• Document version numbers and revision tables usually go out of date.

Maintenance and Review

Ownership and Accountability

Ownership of Confluence spaces, sections, pages, and sub-sections should cascade from the top down:

• Assign a dedicated owner for each space.
• Designate owners for sections and sub-sections.
• Identify specific owners for pages.

Space owners are responsible for allocating ownership roles, with assignments documented in Roles and Responsibilities (R&R) and tracked in Airtable.

Regular Reviews

• Implement a quarterly review process and mark pages with the next review date.

Publishing and Updating the Team

• Owners should choose the most efficient method to relay updates to stakeholders, from simple Confluence notifications to review sessions or Jira tickets for substantial changes.

Feedback Mechanism

• Encourage users to use the feedback section at the bottom of Confluence pages to share suggestions or corrections.