Consistent identification of categories and format is important in order to make a knowledge base as effective as possible. This page provides a style guide for creating mCODE knowledge base (KB) content in a way that optimizes for search and navigation to mCODE concepts.
Creating new pages
Use the "+ New page" button on the Q's and How-To's page. This will ensure that you are using the correct template and that the new page is created in the correct part of the page hierarchy.
- Make the title concise (80 characters or less) so that it appears in full on a keyword search without being truncated.
- Ideally, the most important concept in the page should appear in the page title.
- For Q&A pages: if the full question is too long to fit in the page title, there is an optional "Question" section in the template that can be used to convey an expanded version of the question
Headings within the page
- For Q&A pages, use H2 for the "Question" and "Answer" headings. Use H3, H4, etc. for sub-headings.
- For "how to" pages, use H2 for top-level section headings
The mCODE KB has some pre-defined labels that should be added to every how-to and troubleshooting article created.
- Add the
mcode-kblabel to all articles. This is done automatically by the new page template.
- Add one of the following mCODE category labels to any KB article article referencing an mCODE profile.
- Add the
mcode-processlabel to all KB articles related to the mCODE administrative and operational processes.
- Add the
mcode-generallabel for all other mCODE articles not fitting any of the above categories.
This section in the sidebar uses Confluence's page properties feature to identify:
- Applicable to mCODE version: Which version of mCODE the page applies to. We use the the pessimistic operator
~> 1.0to mean >= 1.0 and < 2.0.
- Page status: This is a status macro that is either IN DEVELOPMENT or PUBLISHED.
This information is aggregated for all KB pages on Q's and How-To's.
- Use the Confluence
Code Blockmacro if the answer includes syntax or development code in a how-to-article.
The example below shows a code block snippet.
The content that appears in the sidebar of KB pages is below. Edit this section of this page to update all the KB pages.