MedBiquitous Knowledgebase
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

MedBiquitous Knowledgebase SOP

Written by: Ben Hsu

Last Modified: August 14, 2020

For a PDF copy, click here.

Change Log

Version No.

Date

Author

Change Notes

1.0

2020-08-14

Ben Hsu

First version of SOP.









Basic User Guide

Introduction:

Welcome to the MedBiquitous Knowledgebase. This site was designed to be a readily accessible repository for information related to the development of MedBiquitous standards.  This guide is designed for users who plan to use this site as a reference and need to understand how to navigate the site.

Terminology

Site – Refers to MedBiquitous Knowledgebase website. Accessible at http://groups.medbiq.org/medbiq.

Space – How Confluence organizes content into meaningful categories. Each space in the MedBiquitous Knowledgebase corresponds to one standard or a set of closely related standards; i.e. Curriculum Inventory has a dedicated space, Competency Object and Competency Framework have a shared space, and so on.

Specification – The explicit set of requirements for a given standard.

Schema – Defines the overall structure of the data standard metadata. Describes the hierarchy of and relationship between elements of the data standard.

Page – The basic unit of organization in the knowledgebase. Basically, just a webpage. Each page houses a certain amount of content.

Parent page – Used to refer to a page that is broader and “higher” in the page hierarchy of a space.

Child Page – Used to refer to a page that is more granular and “lower” in the page hierarchy of a space.


Navigating the Knowledgebase

Searching

If you are new to the Knowledgebase, start here. Use the search bar in the middle of the home page when you are looking for specific topics.

The search function can also be used to search the text within documents. It not only searches each page in the knowledgebase, but also the content of any text documents such as DOCX, XLSX, PDF, TXT, and so on. However, it CANNOT search inside image files like JPG or PNG files.

Page Tree

The Knowledgebase follows a standardized page structure:

  • Charter
  • Specifications and Schemas
  • Implementation Guidelines
  • Use Cases and Scenarios
  • Meeting Archives
  • Resources
    • Media and Publications
    • Document Archives
    • Data Analysis (if applicable)
  • Working Group Members

In some spaces (e.g., Financial Interests), there was initially so little content that some pages (for example, Resources) were left blank. If you wish to add content to these pages, please review the “Adding New Content” portion of the Standard Operating Procedures.

Description of pages

  • Charter – Describes the mission, purpose, and scope of the working group that developed the standard.
  • Specifications and Schemas – Contains links to current specifications and schemas, as well as any changes that may have been made. Also contains information related to changes that are made to the standard (e.g. version 2.0). Also available on medbiq.org.
  • Implementation Guidelines – Information for those who plan to implement the standard.
  • Use Cases and Scenarios – Describes how the standard will play a role in a given situation.
  • Meeting Archives – Contains the meeting minutes of the working group that developed the standard. Useful for looking at the development process of the standard.
  • Resources – a parent page that holds most documents and materials used or produced during the standards development process.
    • Media and Publications – Contains any conference posters, press releases, or publications that resulted from the efforts of the working group. Also contains any documents related to communication strategy.
    • Document Archives – a catch-all category for documents that were used as reference.
    • Data Analysis (if applicable) – Previously created by some working groups to compile resources and draw meaningful findings from them.
  • Working Group Members – a list of members in the working group while the standards were being developed. Also available on medbiq.org.


Getting Started

Home

When you first navigate to https://groups.medbiq.org/medbiq, you will be greeted by the homepage for the MedBiquitous Knowledgebase.

  1. Space Shortcuts/Standards sidebar: Links to the relevant space for each standard.
  2. Search bar: This search bar searches content from each space on the site.
  3. Introduction: Introduction to the knowledgebase.
  4. Frequently Asked Questions: Will populate with answers to commonly asked questions.
  5. Need more help: Gives a contact email if the user needs more assistance.
  6. Other resources: Links to other web resources that the user can reference.
  7. Standard Operating Procedures: Links to a web version of this document. This document was available for download at this page.

Using the standards sidebar (1), you can navigate to any space for a standard.


Standard-related space – Home page


  1. Search bar: You can use the search bar to search for content only in the current space.
  2. Space Shortcuts: Links to the other spaces on the site. You can click the “Knowledgebase Home” space to return to the knowledgebase home page.
  3. Navigation: You can use this page tree to navigate the contents of the space without accessing the sidebar.
  4. Welcome: An introduction to the space and specific standard.
  5. Executive Summary: A summary of the working group’s progress and results.
  6. Communication: How to best reach the working group and access meeting minutes


  1. Browse by topic: Lists the content labels that are found in the space.
  2. Recently updated articles: Lists articles that have recently been updated or edited.
  3. Most popular articles: Lists the most frequently visited pages in the space.

Resources page


  1. Site search bar: Searches for content throughout the entire Knowledgebase.
  2. Navigation sidebar: This is how you get around the space. Click a link to go to that page.
  3. Page tree search bar: Searches for content only within the Resources page and its child pages.
  4. Child page links: Links to and describes each of the child pages


Document Archives

  1. Table & Table Heading: This is how documents are sorted on the Document Archives page. The Table Heading describes what topic the documents discuss (e.g. API Development).
  2. Name: The name or title of the document
  3. Author(s): The people who created the document.
  4. Description: Text describing the content of the document
  5. Year: The year that the document was published or created.

FAQs

To be developed as the knowledgebase is launched.


Advanced User Guide

Introduction

This is a guide designed for users who plan to actively contribute to and maintain the MedBiquitous Knowledgebase.

Adding new content

Before you add content, consider what kind of content you are adding. Search for related information in the space that is relevant to your content.

  • Is it written copy for a page or space?
  • Is it a document?
  • Is it an image or schematic?

Consult the following flowchart for help making this decision:

Creating a new space

Consult with the MedBiquitous Director. Generally, if a new standard is developed, then a new Confluence space should be created to archive documents that are generated during the development of that standard. It should follow the same template for information that are outlined in the SOP.

Creating a new page

Before creating a new page, first consider whether a page already exists that serves a similar purpose. Avoid adding new items to the first level of the space hierarchy.

  1. Go to the page you plan to add the child page to.
    1. If you plan to add a page under first-level hierarchy, go to the space home page.
  2. Click the “create” button. Click the ellipsis if you need to use a template.

  1. Add your content.
  2. Click the “publish” button at the bottom of the page.

Adding new child page to “Resources” page

Before adding a new child page to the Resources page, consider whether your page fits under the categories that already exist. Do not create a new page to house a single document; attach your document to the Document Archives page.

  1. Go to the Resources page.
  2. Follow the “Creating a new page” procedure outlined above.
  3. Return to the Resources page and click the edit button:
  4. Add the title of your new page in Heading 2 font style and write out its purpose in paragraph form below the title.
  5. Link to your new page by highlighting the title text and clicking the “Insert Link” button:
    1. Hint: type “[“ (open square bracket) for a list of links that Confluence thinks is useful.
  6. Go to “Recently Viewed” at the left of the new box.
  7. Select your new page, then click “Insert.”

  1. Click “update” in the editor to save and publish your changes.

Adding images to a page

  1. Open the Page Editor in Confluence by clicking the “edit” button.
  2. Find the image that you wish to attach on your computer.
  3. Drag and drop the image onto the Page Editor.
  4. Resize and format as necessary.
  5. To add accessibility information such as alt text, select the image then click Properties > Title.

Attaching documents

  1. Click the ellipsis at the top-right of the page where you plan to attach the document.
  2. Click “Attachments.”

  1. Use the browse button to upload a document and add comments.
    1. You can also just drag & drop content into the designated box.
    2. You can also click the “attach more files.”
  2. Click the “attach” button at the bottom of the page.

  1. Click the “label” icon in the row of the document that you just attached:
    1. Label the document format and add content-specific tags (describe what’s in the document)
  2. Return to your original page and click the “edit” button.
  3. Write out the title of your file with a short summary and highlight the title of the file.
  4. Click the “Insert Link” button.
  5. Go to “Files.”
  6. Find and select your attachment, then click “Insert.”
  7. Update the page.

Attaching documents to “Document Archives”

The Document Archives pages have a tabular format that organizes the content by topic and lists. This was derived from having multiple child pages.

  1. Attach the document to the Document Archives page as outlined in the “Attaching documents” protocol.
  2. Open the page editor.
  3. In the Document Archives hierarchy, find a heading that best describes the content of your document.
    1. If it doesn’t fit a topic that already exists, create a new table by copying and pasting a table already in the space.
    2. If a table does not exist, open the “document archives” template in Confluence and copy & paste that table into the Document Archives page.
  4. Fill out the information and link your attachment to the document title.

 

Moving pages

There are 2 options for moving pages -either through using the “move” option found in the ellipsis menu, or by accessing the page hierarchy.

Option 1: Hierarchy page

  1. Click the ellipsis at the top right of the page.
  2. Click “view in hierarchy.”
  3. Find the page you want to move then drag and drop.

 

Option 2: Move function

  1. Click the ellipsis at the top right of the page.
  2. Click “Move.”
  3. You can either specify the space and new parent page by typing it in, searching for it, or browsing.
  4. Click move.

 

Labeling & categorization

In Confluence, content tags are called “labels.” Labeling is crucial to improving searchability and filtering of a site or knowledgebase. The Confluence search engine will be able to produce better results if content throughout the Knowledgebase is labeled appropriately.

Due to the scope of this project, a fully-fledged label vocabulary was not delivered with the first version of the redesigned site. However, here are some points to consider:

  1. Tags should fully describe content on the page, which includes the topic area the page describes and what types of content exist on that page.
    1. A page describing a conceptual model for the Competency Framework and Object standards could have the tags “competency-framework, competency-object, definitions, models, diagrams” in addition to other tags that describe the content of that page.
    2. Documents can have their own set of tags. In addition to the tags listed above, a tag noting the document format (e.g. DOCX, PPTX, XLSX) is encouraged.

A good set of guidelines: Mozilla’s MDN Web Docs page on how to properly tag pages in the MDN wiki.

Troubleshooting

Rebuilding the search index

You need admin privileges to do this. If users are having issues with the search function, consider rebuilding the search index.

  1. Click the gear icon at the top right of the site, then click “general configuration.”
  2. In the sidebar, under “Administration,” click “Content Indexing.”
  3. Click “Rebuild.”


Knowledgebase development process

The Confluence site was transitioned with other MedBiquitous intellectual property when it shifted ownership from Johns Hopkins University to the AAMC. The reorganization of the site took place June-August 2020.

We conducted interviews with previous users to understand prior use patterns and how to best restructure and asked current stakeholders how they envisioned the knowledgebase. Interview notes were compiled in an affinity diagram.

Additionally, we requested a literature review from the AAMC Reference Center on information architecture and knowledgebase management and reviewed two textbooks: Information Architecture, 4th Edition by Louis Rosenfeld, Peter Morville, and Jorge Arango; and Everyday Information Architecture by Lisa Maria Martin. These resources were used to inform the architecture laid out in the “Navigating the Knowledgebase” section of the SOP. Once the architecture was designed, the content was copied to new spaces and organized to fit the new architecture.

Rationale for architecture

The new architecture has been designed with searchability in mind. Confluence’s search is very powerful; it can scrape text from PDFs and other formats like PPTX and XLSX.

Because of this powerful search capability, the knowledge base was designed to be “deeper.” Each level has a shorter list of items to scan but will require more clicks to get to the information. A “flat” information architecture involves having more content available closer to the top of the hierarchy. While content is more discoverable this way, this volume of information can be overwhelming to users.

Two examples are shown here, courtesy of Nielsen Norman Group.

Archive Retrieval

Archived versions of the spaces as they were organized prior to June 2020 are available upon request by contacting medbiq@aamc.org.

Further Improvements

Here are some suggested improvements that can be made to the knowledgebase:

  • Individual icons for each space that relate to the standard.


Acknowledgements

Johmarx Patton, MD, MHI

Jeffrey Kaminski, MS

Anne Farmakidis

Tim Willett, MD

David Topps, MD

Rosalyn Scott, MD

J.B. McGee, MD

Tanveer Haq






  • No labels