slopdocs/structure.slopdocs.md

Slopdocs Generation Guidelines for LLMs

Purpose and Audience

Target Audience

This guide is specifically designed for LLM coding agents that generate slopdocs documentation. The content is structured to enable efficient parsing, understanding, and implementation by automated systems.

Primary Goals

• Provide concise, token-efficient documentation optimized for machine consumption
• Deliver practical implementation details over theoretical explanations
• Create consistent documentation that serves as a single source of truth
• Reduce barriers to entry for working with unfamiliar or new technologies
• Minimize computational resources required for documentation generation and consumption
• Document how to use components that are already installed on the system

Writing Style and Tone

Language Characteristics

• Concise and Direct: Use minimal tokens while maintaining clarity
• Unambiguous: Eliminate vague or interpretative language
• Technical Precision: Use accurate terminology without unnecessary verbosity
• Active Voice: Prefer active voice over passive voice for clarity
• Instructional Focus: Write with clear, actionable instructions
• Resource-Efficient: Structure content to minimize processing overhead

Tone Guidelines

• Maintain a professional, technical tone throughout
• Avoid conversational filler and pleasantries
• Focus on what is essential for implementation
• Present information as authoritative guidance
• Use consistent terminology across all documents
• Prioritize factual accuracy over stylistic flourishes

Content Organization Principles

Logical Flow

1. General to Specific: Start with overview, then progress to details
2. Concept to Implementation: Introduce concepts before showing implementation
3. Simple to Complex: Build understanding incrementally
4. Prerequisite First: Cover requirements before usage
5. Problem-Solution: Present practical problems followed by concrete solutions

Concept Separation

• Each major concept should have its own section
• Use clear headings to delineate different topics
• Avoid mixing unrelated concepts in the same section
• Provide clear transitions between related concepts

Terminology Consistency

• Define key terms on first use
• Use consistent terminology throughout the document
• Avoid synonyms for technical terms
• Maintain alignment with established project terminology

Example-Driven Content

• Prioritize practical examples over theoretical explanations
• Include code snippets for implementation guidance
• Provide real-world use cases when applicable
• Show common patterns and best practices
• Focus on examples that solve actual development challenges
• Ensure examples are tested and verified for accuracy

Formatting Guidelines

Markdown Headings

• Use H1 (#) for the document title only
• Use H2 (##) for major sections
• Use H3 (###) for subsections
• Use H4 (####) for detailed sub-subsections
• Avoid going deeper than H4 unless absolutely necessary

Document Summary Requirement

All slopdocs must include a summary section at the end of the document following this exact format:

1. An empty line
2. Three dashes (---) on its own line
3. An empty line
4. The summary text (without a heading)

The summary should be plain text without any heading unless a level 1 heading is absolutely necessary. This format ensures consistency across all documents and provides a clear separation between the main content and the summary. The summary should be written to help LLMs quickly understand if this document is relevant to their needs.

Code Block Formatting

• Use appropriate language identifiers for syntax highlighting
• Include complete, runnable examples when possible
• Add brief comments to explain complex code
• Use inline code () for technical terms and function names

List Usage

• Use numbered lists for sequential steps or ordered information
• Use bulleted lists for unordered collections of items
• Nest lists to show hierarchical relationships
• Keep list items parallel in structure

Table Formatting

• Use tables for comparing options or showing parameter specifications
• Include clear headers that describe column contents
• Keep tables focused and not overly complex
• Use tables to present structured data efficiently

Best Practices for LLM-Generated Documentation

Information Structure for LLM Consumption

1. Keyword Optimization: Include relevant technical terms in headings and content
2. Context Provision: Provide sufficient context in section introductions
3. Self-Contained Sections: Make sections understandable without excessive cross-referencing
4. Summary Sections: Include summaries for complex topics to aid comprehension
5. Token Efficiency: Structure content to minimize processing overhead

Balancing Completeness and Conciseness

• Include all essential information for implementation
• Exclude theoretical background unless directly relevant
• Focus on what is needed to use the component effectively
• Provide references to additional information without duplicating content
• Use links to related documentation rather than repeating information
• Optimize for minimal token usage while maintaining clarity
• Break large documentation into smaller, focused files when content becomes extensive
• Never include installation or build instructions - slopdocs document components that are already installed

Ensuring Information Accuracy and Relevance

• Verify all technical information before inclusion
• Test code examples to ensure they work as described
• Include version information when relevant
• Mark deprecated features clearly
• Regularly review and update content to maintain accuracy
• Take professional responsibility for the accuracy of all content
• Acknowledge limitations and uncertainties in documentation

Handling Version-Specific Information

• Clearly indicate version requirements and compatibility
• Use version-specific sections when necessary
• Provide migration paths for version changes
• Include deprecation notices with timelines
• Document breaking changes prominently

Examples of Good vs. Bad Slopdocs Content

Good Example: Library Documentation

# React Frontend Library

## Overview
React is a JavaScript library for building user interfaces with component-based architecture.

## Usage

javascript import React from 'react';

function Button({ onClick, children }) { return (

<button onClick={onClick}>
  {children}
</button>

); }

## Props Reference
- `onClick`: Function called when button is clicked
- `children`: Content to display inside button

## Integration
Import components and use within React applications following standard patterns.

Bad Example: Library Documentation

# React

React is really popular nowadays. Many developers love using it because it makes building UIs easier. It was created by Facebook and has a big community.

## How to get it
You can install React using npm. Just run this command:

bash npm install react

## Making components
When you want to make a component, you can do something like this. There are many ways to do it, but here's one example:

javascript import React from 'react';

// This is a button component function Button(props) { return (

<button onClick={props.onClick}>
  {props.children}
</button>

); }

I think React is great because you can reuse components and it helps organize your code.

Good Example: API Documentation

# Authentication API

## Overview
Provides JWT-based authentication for user access control.

## Endpoints

### POST /auth/login
Authenticates user and returns access token.

#### Request Body

json { "username": "string", "password": "string" }

#### Response

json { "token": "string", "expiresIn": "number" }

### POST /auth/refresh
Refreshes expired access token using refresh token.

#### Request Body

json { "refreshToken": "string" }

## Error Codes
- 401: Invalid credentials
- 403: Token expired
- 500: Server error

Bad Example: API Documentation

# Auth API

This API handles authentication. It's pretty important for security.

## Login
To login, you need to send a POST request to /auth/login with your username and password. The server will give you back a token if everything is correct.

## Refresh
Sometimes your token will expire, so you can use the refresh endpoint to get a new one. You need to send your refresh token.

## Errors
If something goes wrong, you'll get an error code. 401 means wrong password, 403 means token expired, and 500 means something broke on the server.

Document Structure Template

Standard Sections

1. Title: Clear, descriptive component name
2. Overview: One-paragraph summary of purpose and functionality
3. Prerequisites: Requirements for using the component
4. Installation/Setup: Step-by-step setup instructions
5. Usage: Examples and common use cases
6. API/Interface Reference: Detailed technical reference
7. Integration: How to integrate with other components
8. Troubleshooting: Common issues and solutions
9. Related Documentation: Links to related SlopDocs

Section Guidelines

• Keep sections focused on their primary purpose
• Use consistent section ordering across documents
• Include practical examples in implementation sections
• Provide cross-references to related information
• Maintain appropriate level of detail for each section
• Consider breaking large sections into separate documents when they become too extensive

Quality Assurance Checklist

Content Quality

• All technical information is accurate
• Code examples are tested and functional
• Terminology is consistent throughout
• Content is focused on practical implementation
• Version information is included where relevant

Structure Quality

• Document follows standard section ordering
• Headings are descriptive and properly nested
• Content flows logically from general to specific
• Related concepts are appropriately grouped
• Cross-references are accurate and helpful

Formatting Quality

• Markdown syntax is correct
• Code blocks have appropriate language identifiers
• Lists are properly formatted and parallel
• Tables are well-structured and readable
• Links are functional and relevant

LLM Optimization

• Headers include relevant keywords
• Content is structured for efficient parsing
• Sections are self-contained when possible
• Examples demonstrate practical usage
• Information density is appropriate for machine consumption

Implementation Guidelines for LLMs

Generation Process

1. Analyze Requirements: Understand the component's purpose and scope
2. Identify Audience: Consider both LLM and human consumers
3. Structure Content: Plan sections based on component type
4. Generate Content: Write following style and formatting guidelines
5. Validate Quality: Review against quality checklist
6. Optimize for LLMs: Ensure structure supports machine parsing
7. Review for Resource Efficiency: Verify minimal token usage

Content Generation Best Practices

• Start with a clear outline before generating content
• Use consistent terminology throughout the document
• Include practical examples that demonstrate real usage
• Focus on what developers need to know to implement
• Avoid theoretical background unless directly relevant
• Provide sufficient context for understanding without excessive detail
• Prioritize practical problem-solving approaches
• Ensure all technical claims are verified and accurate
• Break large documentation into multiple focused files when content exceeds 2000 words
• Use additional namespace components to create logical document hierarchies
• Never include installation, build, or setup instructions - document usage of already-installed components

Self-Evaluation Criteria

• Would another LLM be able to understand and use this information?
• Is the content actionable without requiring additional research?
• Are examples complete and functional?
• Is the formatting consistent with other slopdocs?
• Does the document follow all guidelines in this structure guide?
• Does the content demonstrate resource efficiency through conciseness?
• Does the documentation focus on practical problem solving?
• Is the content accurate and professionally responsible?
• Does the document focus on usage rather than installation or building?

---

This guide provides comprehensive writing style, content organization, and formatting guidelines for LLMs generating slopdocs documentation. It establishes standards for creating concise, token-efficient documentation optimized for machine consumption while maintaining human readability. The guide emphasizes practical implementation details, consistent terminology, and resource-efficient content creation to serve as the definitive reference for automated documentation generation.

This guide serves as the definitive reference for LLMs generating slopdocs content. Following these guidelines ensures consistent, high-quality documentation optimized for both machine consumption and human readability while maintaining ethical standards of truth, responsibility, low resource usage, and practical problem solving.