Skip to main content

Adding a New Knowledge Base Article

This guide explains how to add a new article to the OVI General Contracting Knowledge Base system using our Docusaurus platform.

Understanding the Knowledge Base Context​

The OVI-GC Knowledge Base is designed around a comprehensive operating model framework that focuses on organizational efficiency, process management, and continuous improvement. When creating new articles, it's important to understand this context.

Operating Model Framework​

Our KB articles support an operating model approach that prioritizes:

  1. Artifacts: Tangible inputs and outputs that flow through organizational processes
  2. Transformers: Mechanisms (tasks, activities, workflows, processes) that change artifacts
  3. Policies, Procedures, and Specifications: Guidelines and standards governing operations
  4. KPIs: Metrics measuring organizational effectiveness and efficiency

Article Purpose and Value​

Each KB article should:

  • Support one or more components of our operating model
  • Provide clear, actionable information that improves organizational efficiency
  • Connect to broader organizational goals and processes when appropriate
  • Focus on outputs and results rather than just actions and activities

When creating content, consider how your article fits into this framework and supports OVI-GC's approach to organizational management and continuous improvement.

File Structure and Placement​

  1. Determine the appropriate category for your article:

    • Technical Reference - Technical guides, software instructions, IT procedures
    • Procedure - Step-by-step work processes (subdivided into OPERATIONS, PROJECT CONTROLS, ESTIMATING, BUSINESS DEVELOPMENT, etc.)
    • Process - Explanation of workflows involving multiple procedures, should include a swimlane diagram showing the workflow where each swimlane corresponds to the related procedure (subdivided into OPERATIONS, PROJECT CONTROLS, ESTIMATING, BUSINESS DEVELOPMENT, etc., same as Procedures)
    • Policy - Company policies and standards
    • Specifications - Standards that precisely describe the requirements of given artifacts like contracts, reports, permits, etc. (subdivided into OPERATIONS, PROJECT CONTROLS, ESTIMATING, BUSINESS DEVELOPMENT, etc., same as Procedures and Processes)
    • Operating Model - Organizational structure and operational information
    • KPI - Performance metrics for workflows that quantify the outputs of processes and procedures based on their frequency and quality alignment with corresponding specifications. KPIs integrate specifications, procedures, and processes into measurable outcomes.
    • Employees - Employee-specific information

  2. Place your new article in the corresponding directory within the docs/ folder.

    Example file paths:

    docs/technical-reference/new-guide.md
    docs/procedure/construction/new-procedure.md
    docs/policy/new-policy.md

Article Formatting​

File Naming​

  • Use kebab-case (lowercase with hyphens) for filenames
  • Keep filenames descriptive but concise
  • Example: identity-setup.md or change-orders.md
  • Name files consistently with other files in the same folder

Docusaurus uses a sidebar configuration file to control the navigation structure. When adding a new article:

  1. Locate the sidebar configuration file - typically in sidebars.js at the root of your project

  2. Determine if you need to update the sidebar:

    • If your article is going into an existing category that auto-discovers documents, no changes may be needed
    • If your article needs to be explicitly added to the sidebar structure, follow the pattern below

  3. Update the sidebar configuration if necessary:

// Example sidebars.js structure
module.exports = {
  mainSidebar: [
    {
      type: 'category',
      label: 'Technical Reference',
      items: [
        'technical-reference/index',
        'technical-reference/new-guide', // Add your new article here (no file extension)
      ],
    },
    // Other categories...
  ],
};
note

If your Docusaurus setup uses automatic sidebar generation, you may only need to add the proper sidebar_position frontmatter to your document to control its placement.

Frontmatter​

Each article must begin with YAML frontmatter:

---
title: Your Article Title
description: A brief description (1-2 sentences) of what the article covers
slug: optional-custom-url-path
sidebar_position: 3
sidebar_label: Optional Shorter Sidebar Title
tags:
  - relevant
  - tags
  - here
---

Essential Frontmatter Fields​

  • title: The title of your article (appears at the top of the page)
  • description: Brief summary for SEO purposes
  • sidebar_position: Controls the order in the sidebar navigation
  • tags: Relevant keywords for searchability

Optional Frontmatter Fields​

  • slug: Custom URL path (defaults to the filename)
  • sidebar_label: A shorter title that appears in the sidebar
  • hide_table_of_contents: Set to true to hide the right-side table of contents

Content Structure​

  1. Start with a level 1 heading (# Title) that matches or expands on your frontmatter title
  2. Use hierarchical headings (## for main sections, ### for subsections)
  3. Include a brief introduction after the title
  4. Organize content logically with clear section headings
  5. Use numbered lists for sequential procedures
  6. Use bullet points for non-sequential lists
  7. Include a conclusion or summary when appropriate

Handling Scribehow Exports​

When working with exports from Scribehow (a tool that generates step-by-step visual guides), follow these guidelines:

Processing the Export​

  1. Review the entire Scribehow export to understand the workflow
  2. Identify images that need additional context or explanation
  3. Organize the steps in a logical sequence that follows our KB format

Enhancing Images with Narrative Text​

Images from Scribehow exports often need additional context to be fully valuable:

  1. Add descriptive text before each image that explains:

    • What the user will accomplish in this step
    • Why this step is important
    • Any special considerations or potential issues

  2. Follow each image with detailed instructions that:

    • Clarify what is shown in the image
    • Provide additional context not visible in the screenshot
    • Explain alternative approaches when applicable

  3. Use admonitions to highlight important information:

    :::tip
    This step is particularly important because it affects later configuration options.
    :::

  4. Organize related screenshots under clear section headings to improve navigation

Example of Enhanced Scribehow Content​

## Setting Up User Permissions

1. **Navigate to the Permissions Panel**
   
   From the dashboard, access the user management section to configure permissions.
   
   ![Screenshot of dashboard with user management highlighted](https://amazon-url-to-image.jpeg)
   
   The User Management section can be found in the left sidebar. If you don't see it, ensure you have administrator privileges.

2. **Select the User Group**
   
   Choose the appropriate user group to modify permissions efficiently.
   
   ![Screenshot of user group selection](https://amazon-url-to-image.jpeg)
   
   :::note
   Changes to user groups will affect all members. For individual exceptions, use the "Single User Override" option instead.
   :::

Alignment with Syntax Standards​

All KB articles must adhere to our established syntax standards found in the Docusaurus Syntax Guide. Review this guide before creating or editing articles. Key requirements include:

Essential Formatting Elements​

  1. Use proper heading hierarchy (# for title, ## for sections, ### for subsections)
  2. Implement admonitions for notes, warnings, tips, and other callouts
  3. Format code blocks with appropriate language tags for syntax highlighting
  4. Use tables for comparative information

Advanced Elements to Include​

When appropriate, enhance your articles with these advanced formatting options:

  1. Tabbed content for alternative methods or environments:

    import Tabs from '@theme/Tabs';
    import TabItem from '@theme/TabItem';

    <Tabs>
      <TabItem value="windows" label="Windows" default>
        Windows-specific instructions...
      </TabItem>
      <TabItem value="mac" label="Mac">
        Mac-specific instructions...
      </TabItem>
    </Tabs>

  2. Mermaid diagrams for workflows and processes:

    ```mermaid
    graph TD
        A[Start] --> B{Decision Point}
        B -->|Yes| C[Action 1]
        B -->|No| D[Action 2]

  3. Interactive checklists for procedure completion tracking:

    - [ ] Step 1
    - [ ] Step 2
    - [x] Completed step

Text Styling Standards​

  • Use bold for UI elements, button names, and emphasis
  • Use italics for secondary emphasis and introduced terms
  • Use code formatting for file paths, commands, and code snippets

Formatting Guidelines​

Text Formatting​

  • Use bold for emphasis and UI elements (**bold**)
  • Use italics for secondary emphasis (*italics*)
  • Use code formatting for code, commands, or file paths (`code`)

Admonitions​

Use admonition blocks for notes, warnings, tips, etc. Docusaurus uses a triple colon ::: syntax for admonitions, which is different from MkDocs (which uses !!!):

:::note
This is a note with important information.
:::

:::tip[Custom Title]
This is a tip with a custom title.
:::

:::info
This provides additional information.
:::

:::caution
This is a warning message.
:::

:::danger
This indicates critical information.
:::

:::success
This indicates a successful outcome or completion.
:::

Important: Make sure to use the triple colon ::: syntax, not the MkDocs !!! syntax. The content inside the admonition should not be indented.

[Link Text](https://example.com)

For internal links to other documents, use relative paths:

[Another Article](../category/article-name)

Image Handling​

Image Storage​

  1. Static Assets: Store images in the Docusaurus static folder

    • Example: static/img/technical-reference/your-image.png

  2. Amazon-hosted Images: Preserve the full Amazon URLs as-is

    • Do not modify or shorten Amazon S3 or CloudFront URLs

Image Insertion​

  1. For static assets:

    ![Alt Text](/img/technical-reference/your-image.png)

    To center an image with a caption:

    <div style={{textAlign: 'center'}}>
      <img src="/img/technical-reference/your-image.png" alt="Alt Text" />
      <p><em>Image caption here</em></p>
    </div>

  2. For Amazon-hosted images:

    • Preserve the complete URL including all query parameters
    ![Alt Text](https://ajeuwbhvhr.cloudimg.io/colony-recorder.s3.amazonaws.com/files/2024-09-03/e65c0dfd-8a42-40e2-9cb5-ec243e51f816/user_cropped_screenshot.jpeg?tl_px=0,0&br_px=462,73&force_format=jpeg&q=100&width=860&wat_scale=76&wat=1&wat_opacity=0.7&wat_gravity=northwest&wat_url=https://colony-recorder.s3.us-west-1.amazonaws.com/images/watermarks/FB923C_standard.png&wat_pad=426,63)

Connecting to Operating Model Concepts​

When creating KB articles, especially for procedures, policies, or specifications, try to:

  1. Link to Artifacts: Identify any inputs or outputs the article relates to
  2. Reference Transformers: Mention if the article supports a specific task, activity, workflow, or process
  3. Consider KPIs: Note any metrics that might measure the effectiveness of the process
  4. Use Diagrams: When appropriate, include Mermaid diagrams to illustrate process flows:
```mermaid
graph LR
    A[Input Document] --> B[Review Process]
    B --> C[Approved Document]
    B --> D[Rejected Document]
    D --> E[Revision Process]
    E --> B

This helps ensure all KB articles support the overall operating model framework and provide consistent value.

## Checklists

For procedures, consider including a completion checklist:

```markdown
## Checklist

- [ ] Step 1
- [ ] Step 2
- [ ] Step 3
- [x] Completed step

Testing Your Article​

Before submitting your article:

  1. Verify all links work correctly
  2. Ensure images display properly
  3. Check for formatting errors
  4. Confirm all frontmatter fields are completed
  5. Validate hierarchical structure and logical flow
  6. If possible, preview your changes using the Docusaurus development server: 
    npm run start

Publishing​

  1. Place your completed markdown file in the appropriate directory
  2. If you've added new images, ensure they're in the correct static asset folder
  3. The site will automatically rebuild with your new content once changes are committed and deployed

Example Article Structure​

---
title: Process Title
description: A comprehensive guide for performing a specific process
slug: process-title
sidebar_position: 4
tags:
  - process
  - relevant
  - tags
---

# Process Title

## Introduction
Brief overview of what this process is and why it matters.

## Procedure

1. **First Step**
   Detailed explanation...
   
   ![Screenshot of first step](/img/process/step1.png)

2. **Second Step**
   Detailed explanation...
   
   :::note
   Important information about this step.
   :::

3. **Third Step**
   Detailed explanation...

## Checklist

- [ ] Step 1 completed
- [ ] Step 2 completed
- [ ] Step 3 completed

:::success[Completion]
Once all steps are complete, the process is finished.
:::

MDX Features​

Docusaurus supports MDX, which allows you to use React components directly in your markdown files. This can be especially useful for creating interactive or complex content:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="step1" label="Step 1" default>
    Content for step 1
  </TabItem>
  <TabItem value="step2" label="Step 2">
    Content for step 2
  </TabItem>
</Tabs>

When used appropriately, MDX can significantly enhance your documentation, but should only be used when standard markdown isn't sufficient.

Questions and Support​

If you have questions about creating or modifying KB articles, please reach out to the documentation team for assistance. We're here to help ensure the knowledge base maintains high quality and consistency across all articles.