Managing your documentation is more than just writing text; it's about organizing a clear, navigable structure for your users. This guide covers the end-to-end lifecycle of your documentation, including creating the core structure, organizing content entries, and managing media assets.

Whether you are building a new knowledge base from scratch or maintaining an existing one, understanding how these pieces fit together will help you keep your content organized and accessible.

Core Concepts

Before diving into the workflows, it is helpful to understand the hierarchy of your documentation structure.

flowchart TD
    Org["Organization"] --> Doc["Documentation (Project)"]
    Doc --> Sec["Section"]
    Sec --> Ent1["Doc Entry (Page/Folder)"]
    Sec --> Ent2["Doc Entry (Page/Folder)"]
    Ent1 --> Child["Child Entry"]
    Doc -.-> Ast["Assets (Images, Files)"]

Setting Up Your Documentation

Creating a new documentation project is the first step in your content lifecycle.

1. 1

   Create the Documentation Container

   Start by creating a new documentation project under your organization. This acts as the top-level wrapper for all your versions, sections, and pages.

2. 2

   Configure Settings

   Update the documentation configuration to set your default preferences, such as branding, navigation styles, and metadata visibility.

3. 3

   Build Your Sections

   Divide your documentation into logical sections (e.g., "Getting Started", "API Reference", "Tutorials").

Initialization Options

When creating a new documentation project, you can initialize it using several methods depending on your starting point:

• Blank Scaffold: Start with a clean slate and default structure.

• AI Prompt: Generate a starting structure using an AI prompt.

• File Import: Upload existing documentation files.

• OpenAPI/Swagger: Automatically generate API references from an OpenAPI spec.

• GitHub Repository: Sync content directly from a repository.

• Website Import: Import an existing website.

• Preset Template: Use built-in templates for common project types.

Managing Versions

Documentation projects often require multiple versions (e.g., v1, v2) to support different releases of your product. You can create new versions, update existing ones, delete deprecated versions, and set a specific version as the default for your readers.

Organizing Content Entries

Entries are the building blocks of your documentation. They can be individual articles, API references, or folders that contain other entries.

Creating and Managing Entries

You have several options for adding content to your sections:

Moving and Reordering

As your documentation grows, you will inevitably need to reorganize it.

• Reordering: You can change the display order of entries within the same parent folder or section. This is useful for curating the reading flow of a tutorial.

• Moving: If an entry belongs in a different category entirely, you can move it to a different parent entry or a completely new section.

AI-Assisted Authoring

GitDocAI provides built-in AI tools to accelerate your documentation workflow:

• Edit Content: Use AI to refine, rewrite, or format your documentation entries directly.

• Generate Images: Create custom images using AI and store them automatically as documentation assets.

Managing Assets

Assets include images, downloadable files, and other media that enrich your documentation. Assets are scoped to the documentation level, meaning they can be reused across different versions and sections.

Asset Lifecycle

1. Upload: Add a new asset file to your documentation project.

2. Update Metadata: Modify the asset's metadata (like alt text, descriptions, or tags) to improve accessibility and searchability.

3. Serve: Use the generated asset URL to embed the file directly into your documentation entries.

4. Delete: Remove outdated or unused assets to keep your project clean.

Frequently Asked Questions