Documentation management

Introduction

ApiShare provides a centralized documentation system that enables organizations to create, manage, and share structured knowledge across teams. The Documentation Catalog serves as a repository for tutorials, guidelines, and other essential resources, ensuring easy access and version control. Documentation in ApiShare is editable through a rich text editor, supports visibility settings, and offers versioning capabilities for historical tracking.

Managing documentation

Creating a new documentation entry

Prerequisites:

• The user must have editing permissions (Owner, Editor, or equivalent role).

Steps:

1. Navigate to Documentation in the main sidebar.

2. Click Create New Documentation.

3. Enter the Title and select the Category.

4. Click Create, which redirects to the Documentation Editor.

Post-Conditions:

• A new documentation entry is created and listed in the Documentation Catalog.

Tips:

• Categories are predefined and cannot be modified.

Editing a documentation entry

Prerequisites:

• Only Owners, Editors, or Administrators can edit documentation.

Steps:

1. Open the Documentation Catalog and select the document.

2. Click Edit to modify metadata and content.

3. Use the rich text editor to update information.

4. Click Save to confirm changes.

Post-Conditions:

• The documentation is updated with the new content.

Creating a new version of a documentation entry

Steps:

1. Open the documentation entry.

2. Click the three-dot menu and select New Version.

3. A new version is created, inheriting metadata and visibility settings.

Post-Conditions:

• A separate version of the documentation is created and can be modified independently.

Tips:

• Previous versions remain read-only and cannot be edited.

Deleting a documentation entry

Steps:

1. Open the documentation entry.

2. Click the three-dot menu and select Delete.

3. Confirm the deletion.

Post-Conditions:

• The selected documentation version is permanently removed.

Tips:

• Deleting a version does not remove all versions of the documentation.

Managing documentation content

Adding and managing pages

Steps:

1. Open the documentation entry.

2. Click Add Page and enter a title.

3. Confirm to update the page list.

4. Click on a page title to edit its content.

Post-Conditions:

• A new page is added to the documentation.

Tips:

• Pages inherit visibility settings from the documentation unless customized.

Editing content using the rich text editor

Steps:

1. Open a documentation page.

2. Click Edit in the top-right corner.

3. Modify the content using formatting tools:

   • Headers (H1-H6)

   • Bold, Italics, Underline, Strikethrough

   • Text Alignment, Lists, Links, Quotes, Tables

   • Undo/Redo (via toolbar or keyboard shortcuts)

4. Click Save to apply changes.

Post-Conditions:

• The documentation page is updated with new formatting.

Tips:

• Use Markdown Mode for advanced text styling.

Enabling markdown support

Steps:

1. Open the Documentation Editor.

2. Click the Markdown button in the toolbar.

3. Toggle between Markdown input and preview mode.

Post-Conditions:

• The text editor switches to Markdown-based formatting.

Tips:

• Markdown can be used for structured formatting but must be enabled manually.

Managing visibility

Configuring documentation visibility

Prerequisites:

• Only Owners can modify visibility settings.

Steps:

1. Open the Documentation Visibility section.

2. Select one of the following visibility options:

   • Full Access: Anyone (including guests) can view.

   • Custom Access: Restricts access to specific organizations.

   • Public access: Anyone can view, including visitors

   • Inherit Access from Documentation:

     (available for pages only): Pages adopt the same visibility as the main document.

3. Click Save.

Post-Conditions:

• The visibility settings are applied to the documentation and its pages.

Tips:

• Each version maintains independent visibility settings.

• Provided that the showcase feature is available and activated, the Public access option allows the documentation to be visible in the Public showcase even without needing an account

Searching and navigating documentation

Using the search bar

Steps:

1. Navigate to the Documentation Catalog.

2. Use the search bar to filter results by:

   • Title

   • Summary

   • Category

   • Owner

   • Editors

   • Tags and Labels

3. Click the Search Icon to refresh results.

Post-Conditions:

• The search results display relevant documentation entries.

Tips:

• Click the Clear ("X") Button to reset filters.

Browsing the results grid

Steps:

1. Open the Documentation Catalog.

2. Browse the result cards displaying:

   • Category and Version

   • Title and Summary

   • Tags, Owner, Last Update Date

3. Click on a Title to access the full document.

Post-Conditions:

• The selected documentation opens for viewing or editing.

Versioning and history management

Viewing documentation versions

Steps:

1. Open a documentation entry.

2. Click on the Version Selector at the top.

3. Choose a version from the list.

Post-Conditions:

• The selected version is displayed in read-only mode.

Tips:

• Older versions cannot be edited but can be restored.

Restoring a previous version

Steps:

1. Navigate to the Versions section.

2. Select an older version.

3. Click Restore (Fork) to create a copy.

Post-Conditions:

• A new version is created, inheriting content from the selected version.

Tips:

• Restoring creates a new version; it does not overwrite existing ones.

Deleting a version

Steps:

1. Navigate to the Versions section.

2. Select the version to delete.

3. Click Delete and confirm.

Post-Conditions:

• The selected version is permanently removed.

Tips:

• The latest version cannot be deleted.

Documentation management best practices

1. Use Categories and Tags: Helps with organization and searchability.

2. Maintain Version History: Avoid unnecessary deletions and ensure information traceability.

3. Set Proper Visibility: Control access based on organization and security needs.

4. Use Markdown for Structured Formatting: Enables better readability and formatting control.

5. Regularly Review and Update Documentation: Keeps information accurate and relevant.