slopdocs

Slopdocs: A Manifesto for AI-Readable Documentation

What is Slopdocs?

Slopdocs is a documentation system designed specifically for Large Language Models (LLMs) and AI coding agents. Think of it as a straightforward, no-nonsense way to organize technical information that machines can efficiently process and use.

The name "slopdocs" comes from the term "AI slop" - those endless streams of generated content that LLMs produce. We're embracing the joke: if AI is going to generate slop anyway, we might as well give it properly structured slop to work with.

Why Does Slopdocs Exist?

When AI systems generate code, they need clear, concise information to work with. Traditional documentation often contains conversational filler, marketing language, or unnecessary background information that increases processing costs and reduces efficiency.

Slopdocs solves this problem by providing:

• Token-efficient content that minimizes computational resources
• Consistent structure that makes information easy to find and parse
• Practical focus on implementation details rather than theoretical concepts
• Ethical guidelines that ensure accuracy, responsibility, and resource efficiency

How Does It Work?

Slopdocs follows a simple but effective organizational system:

File Organization

Instead of complex folder structures, slopdocs uses a flat file system with a naming convention that tells you exactly what each file contains. All files live in a single directory (/usr/share/slopdocs) and use dot-separated names like:

• library.react.frontend.md - Documentation for React frontend library
• utilities.docker.build.md - Docker build utilities
• stack.node.versions.md - Node.js version information
• structure.microservices.architecture.md - Microservices architecture patterns
• ethics.ai.responsible.md - Responsible AI guidelines
• library.react.frontend.components.buttons.md - React button components (example of deeper nesting)
• library.json-glib.parsing.md - JSON-GLib parsing utilities (correct nesting)
• library.json.glib.parsing.md - Incorrect - breaks logical hierarchy

The dot-separated naming creates logical nesting structure. Use dots to group related components (e.g., json-glib as a single component). You can use as many sub-components as needed to create logical, well-organized documentation. Large documents should be broken into smaller, focused files when they become extensive.

This approach makes it easy for AI systems to find exactly what they're looking for without navigating complex directory structures.

Content Structure

Each slopdocs document follows a consistent format:

1. Clear title describing what the document covers
2. Brief overview explaining the purpose and functionality
3. Practical information like installation steps, usage examples, and API references
4. Implementation details that AI systems actually need
5. Summary section that helps AI systems quickly determine if the document is relevant

The writing style is direct and unambiguous, avoiding conversational filler and focusing on what AI systems need to know to get things done.

Who Uses Slopdocs?

Slopdocs is designed for:

• AI coding agents that need efficient, parseable documentation to generate code
• LLMs that require structured information to provide accurate responses
• Documentation systems that need to be machine-readable first and foremost
• Anyone who happens to read the documentation (any human benefit is purely accidental)

What Makes Slopdocs Different?

Ethical Approach

Unlike documentation systems that might prioritize SEO or marketing, slopdocs is built on four core ethical principles:

1. Truth - All information is verified and accurate
2. Responsibility - Content is professionally accountable and maintained
3. Low Resource Usage - Information is presented efficiently to minimize computational costs
4. Practical Problem Solving - Focus on real-world applications and solutions

AI-Optimized

Slopdocs is specifically designed to be easily processed by AI systems. This optimization means:

• Consistent formatting that machines can parse reliably
• Keyword optimization that improves searchability
• Token efficiency that reduces computational costs

Community-Driven

While slopdocs has established guidelines, it's meant to evolve based on real-world use. The system prioritizes practical feedback and continuous improvement over rigid adherence to rules.

This Repository IS Slopdocs

This repository doesn't just contain documentation about slopdocs - it is slopdocs. The files in this repository (apart from this readme) are themselves slopdocs, serving as both documentation and a reference implementation of the slopdocs system.

LLM agents can use these slopdocs as a template and reference to generate slopdocs for other projects, such as new libraries, frameworks, or technical systems. This self-documenting approach demonstrates the practical application of slopdocs principles.

Here are the key documents to check out:

• structure.slopdocs.md - Detailed guidelines for writing slopdocs
• structure.slopdocs.filesystem.md - How the file organization system works
• ethics.slopdocs.md - The ethical principles behind slopdocs

Examples in Practice

Traditional Documentation vs. Slopdocs

Traditional approach:

"React is an incredibly popular JavaScript library that has revolutionized the way developers think about building user interfaces. Created by Facebook, React has gained massive adoption due to its component-based architecture and virtual DOM implementation..."

Slopdocs approach:

"React is a JavaScript library for building user interfaces with component-based architecture. It uses a virtual DOM for efficient updates and provides hooks for state management."

The slopdocs version conveys the same essential information in about half the words, making it more efficient for AI processing.

Real-World Application

When an AI coding agent needs to implement a React component, it can quickly locate library.react.frontend.md and extract the exact implementation details needed without processing unnecessary conversational content.

This efficiency translates to faster response times, lower computational costs, and more accurate code generation.

The Bottom Line

Slopdocs isn't trying to revolutionize documentation with fancy features or complex systems. Instead, it offers a straightforward, efficient approach that works well for AI systems. By focusing on what actually matters—clear, accurate, practical information—it reduces computational costs and improves the quality of AI-generated code.

Whether you're an AI system looking for efficient documentation or a human who happens to stumble upon these files, slopdocs provides a practical solution that gets the job done without unnecessary complexity.