Libx Sample Documentation

Editing Documents

Learn how to edit and maintain documentation so it stays accurate, useful, and current.

Editing Workflow

1. Review and Plan

Before making changes:

  • Identify the goal: What needs to be updated or improved?
  • Check current state: Read through the existing content
  • Plan changes: Outline what needs to be modified, added, or removed
  • Consider impact: How will changes affect related documents?

2. Make Incremental Changes

  • Start small: Make one logical change at a time
  • Test frequently: Verify changes work as expected
  • Preview locally: Run pnpm --filter=sample-docs dev to confirm formatting
  • Regenerate navigation: Run pnpm build:sidebar after renaming files or categories
  • Check links: Ensure all references remain valid

3. Review and Finalize

  • Proofread: Check for typos, grammar, and clarity
  • Validate structure: Ensure logical flow and organization
  • Adjust metadata: Update frontmatter where needed
  • Test thoroughly: Verify all examples and instructions work

Common Editing Tasks

Updating Content

When updating existing content:

Before:

## Installation

You can install our package using npm:

    npm install @our-package/core

After - Added more package managers:

## Installation

You can install our package using your preferred package manager:

    # Using npm
    npm install @our-package/core

    # Using yarn
    yarn add @our-package/core

    # Using pnpm
    pnpm add @our-package/core

Improving Examples

Make examples more comprehensive:

// Before: Basic example
const app = createApp();

// After: Complete example with error handling
import { createApp } from '@our-package/core';

const app = createApp({
  debug: process.env.NODE_ENV === 'development',
  theme: 'light'
});

app.start().catch(error => {
  console.error('Failed to start app:', error);
});

Adding Cross-References

Link related content:

<!-- Before -->
The sidebar will automatically update when you add new files.

<!-- After -->
The sidebar will automatically update when you add new files. 
See [sidebar auto-generation](/v2/en/02-components/04-sidebar-generation) for details.

Frontmatter Updates

This documentation system keeps frontmatter minimal because automation handles the rest:

---
title: "Document Title"
description: "Brief description of what this document covers"
---

These pieces are handled automatically:

  • Navigation: Previous/next links from the file structure
  • Ordering: Numerical prefixes such as 01- and 02-
  • Categorization: Directory names like 01-guide or 02-components
  • Dates: Publication metadata inferred from Git history

Content Improvement Strategies

Enhance Clarity

Before:

Configure the app with the settings.

After:

Configure the app by passing an options object to `createApp()`:

    const app = createApp({
      debug: true,
      theme: 'dark',
      apiUrl: 'https://api.example.com'
    });

Add Visual Elements

Include images, diagrams, or components to clarify concepts:

<!-- Before: Text only -->
The sidebar shows all available documents organized by category.

<!-- After: With visual aid -->
The sidebar shows all available documents organized by category:

![Sidebar example](/images/sidebar-screenshot.png)

For interactive navigation, see [sidebar auto-generation](/v2/en/02-components/04-sidebar-generation) and the [tabs component](/v2/en/02-components/03-tabs).

Provide Context

Explain why something matters:

Before: Just instructions

Set `debug: true` in development.

After: With context

Set `debug: true` in development to enable detailed error messages and performance metrics:

    const app = createApp({
      debug: process.env.NODE_ENV === 'development'
    });

This helps identify issues during development but should be disabled in production for performance.

Advanced Editing Techniques

Using MDX Components

Enhance documentation with interactive components:

import { Tabs, TabItem, Icon } from '@docs/ui';

## Package Manager Instructions

<Tabs>
  <TabItem label="npm">
    {/* bash code block */}
    npm install @our-package/core
  </TabItem>
  <TabItem label="yarn">
    {/* bash code block */}
    yarn add @our-package/core
  </TabItem>
  <TabItem label="pnpm">
    {/* bash code block */}
    pnpm add @our-package/core
  </TabItem>
</Tabs>

<Icon name="info" /> Choose the package manager that matches your project setup.

Creating Callouts

Use components to highlight important information:

import { Alert } from '@docs/ui';

<Alert type="warning">
  <Icon name="triangle-alert" />
  **Important:** Always backup your data before upgrading.
</Alert>

<Alert type="info">
  <Icon name="info" />
  **Tip:** Use the `--dry-run` flag to preview changes first.
</Alert>

Code Annotations

Add explanations to code blocks:

import { createApp } from '@our-package/core';

const app = createApp({
  // Enable debug mode for development
  debug: process.env.NODE_ENV === 'development',
  
  // Set the UI theme
  theme: 'light',
  
  // Configure API endpoints
  apiUrl: process.env.API_URL || 'https://api.example.com'
});

// Start the application
await app.start();

Quality Checklist

Before finalizing edits, verify:

  • Accuracy: All information is correct and current
  • Completeness: No missing steps or information
  • Clarity: Easy to understand for the target audience
  • Consistency: Matches style and terminology of other docs
  • Links: All internal and external links work
  • Examples: Code examples are tested and functional
  • Metadata: Frontmatter is updated appropriately
  • Structure: Logical flow and proper heading hierarchy

Collaboration Guidelines

Making Suggestions

When editing others’ work:

  • Be constructive: Focus on improving clarity and accuracy
  • Explain changes: Provide rationale for significant modifications
  • Preserve voice: Maintain the original author’s writing style
  • Test changes: Verify that your edits don’t break anything

Review Process

For team documentation:

  1. Draft changes in a feature branch
  2. Preview locally to verify formatting and links
  3. Request review from subject matter experts
  4. Address feedback and make necessary adjustments
  5. Merge changes after approval

Next Steps

Now that you understand editing best practices: