18 KiB
18 KiB
Blog to Documentation Integration Plan
Overview
This document maps blog posts to relevant documentation chapters and provides enhanced introductions for main documentation articles to improve educational value.
Blog Post to Documentation Mapping
Chapter 1: Run and Talk (Installation & Quick Start)
Related Blog Posts:
- "Escape from Bigtech" - Alternative to proprietary solutions
- "Why Pragmatismo Selected Open Source" - Philosophy behind the platform
- "Cost-Effective Bot Orchestration" - Economic benefits of self-hosting
Enhanced Introduction:
# Chapter 01: Run and Talk
Welcome to General Bots - your journey to AI independence starts here. In a world dominated by expensive, proprietary AI solutions, General Bots offers a refreshing alternative: a complete, open-source AI platform that you control entirely.
## Why General Bots?
Before diving into installation, let's understand what makes General Bots different:
1. **Complete Ownership**: Unlike SaaS solutions that lock your data in the cloud, General Bots runs on your infrastructure. Your conversations, your data, your rules.
2. **Zero-to-AI in Minutes**: Our bootstrap process sets up everything - database, storage, vector search, and AI models - with a single command. No DevOps expertise required.
3. **Cost-Effective**: As explained in our post ["Cost-Effective Bot Orchestration"](/blog/cost-effective-bot-orchestration), running your own AI infrastructure can be 10x cheaper than cloud services at scale.
4. **Privacy First**: Your data never leaves your servers. Perfect for healthcare, finance, or any privacy-conscious application.
## What You'll Learn
This chapter guides you through:
- Installing General Bots with one command
- Understanding the bootstrap process
- Having your first AI conversation
- Exploring the self-contained architecture
## Further Reading
- [Why We Chose Open Source](/blog/why-pragmatismo-selected-open-source)
- [Escape from BigTech](/blog/escape-from-bigtech)
- [The Hidden Costs of SaaS](/blog/saas-hidden-costs)
Chapter 2: About Packages
Related Blog Posts:
- "Ready-to-Use AI Templates" - Pre-built solutions
- "Digital Twins" - Advanced bot personalities
- "No Forms" - Conversational UI philosophy
Enhanced Introduction:
# Chapter 02: About Packages
General Bots revolutionizes AI development through its unique package system. Instead of complex programming, you work with templates - simple, powerful building blocks that anyone can understand and modify.
## The Template Revolution
Traditional AI development requires teams of engineers. General Bots changes this paradigm. As discussed in ["BASIC for Everyone"](/blog/basic-for-everyone), we believe AI should be accessible to domain experts, not just programmers.
## Package Types at a Glance
1. **.gbai** - Complete bot personalities ([Digital Twins](/blog/digital-twins))
2. **.gbdialog** - Conversation flows in simple BASIC
3. **.gbkb** - Knowledge bases that give your bot expertise
4. **.gbot** - Configuration without code
5. **.gbtheme** - Visual customization
6. **.gbui** - Interface templates ([No Forms philosophy](/blog/no-forms))
## Why Templates Matter
Templates democratize AI development:
- **Business analysts** can create conversation flows
- **Subject matter experts** can build knowledge bases
- **Designers** can customize interfaces
- **No coding required** for most tasks
## Success Stories
See how organizations use templates:
- Customer service automation ([Ready-to-Use Templates](/blog/general-bots-ai-templates))
- Personal productivity bots ([Digital Twins](/blog/digital-twins))
- Enterprise workflows without forms ([No Forms](/blog/no-forms))
## Next Steps
- Explore each package type in detail
- Download pre-built templates
- Create your first custom package
Chapter 3: Knowledge Base (gbkb)
Related Blog Posts:
- "LLM Myths in 2025" - Understanding AI limitations
- "Illusion of Intelligence" - How knowledge bases create real value
- "What is LLM?" - Foundation concepts
Enhanced Introduction:
# Chapter 03: gbkb Knowledge Base Reference
Knowledge is power, and in AI, structured knowledge is everything. The .gbkb system transforms your documents, websites, and data into queryable intelligence that enhances your bot beyond generic LLM responses.
## Beyond Generic AI
As we explore in ["LLM Myths in 2025"](/blog/llm-myths-2025), large language models have limitations. They can't know your specific business rules, your product documentation, or your internal procedures. That's where .gbkb comes in.
## The Knowledge Advantage
Generic LLMs give generic answers. Knowledge bases provide:
- **Accuracy**: Responses based on your actual documentation
- **Consistency**: Same answer every time for critical information
- **Control**: You decide what information is available
- **Updates**: Change knowledge without retraining models
## Understanding the Technology
Before diving deep, understand the foundations:
- [What is LLM?](/blog/what-is-llm) - Core concepts
- [The Illusion of Intelligence](/blog/illusion-of-intelligence) - Why context matters
- [Beyond Chatbots](/blog/beyond-chatbots) - Real business applications
## Real-World Applications
Knowledge bases power:
- Customer support with product documentation
- HR bots with company policies
- Legal assistants with case law
- Medical bots with treatment protocols
## What You'll Master
This chapter teaches you to:
- Build knowledge bases from documents
- Index websites automatically
- Implement semantic search
- Optimize retrieval accuracy
- Manage knowledge updates
## Performance Tips
- Structure documents for optimal chunking
- Use metadata for better filtering
- Implement feedback loops for improvement
Chapter 4: User Interface (.gbui)
Related Blog Posts:
- "No Forms" - Conversational UI philosophy
- "Deswindonization" - Breaking free from proprietary UIs
- "Beyond Chatbots" - Rich interaction patterns
Enhanced Introduction:
# Chapter 04: .gbui User Interface Reference
The future of user interfaces isn't more forms and buttons - it's conversation. The .gbui system lets you create rich, responsive interfaces that adapt to how humans actually communicate.
## The End of Forms
Traditional software forces users into rigid forms. As explored in ["No Forms"](/blog/no-forms), conversational interfaces are more natural, more flexible, and more powerful. Users describe what they need in their own words, and the system understands.
## Breaking Free from Constraints
["Deswindonization"](/blog/deswindonization) isn't just about operating systems - it's about breaking free from rigid UI paradigms. With .gbui templates, you can:
- Create interfaces that work everywhere
- Build once, deploy to web, mobile, and desktop
- Customize without vendor lock-in
## Beyond Simple Chat
While chatbots are the foundation, modern AI interfaces need more. ["Beyond Chatbots"](/blog/beyond-chatbots) shows how .gbui enables:
- Rich media interactions
- Multi-modal inputs (voice, images, files)
- Contextual suggestions
- Workflow integration
- Real-time collaboration
## Template Philosophy
.gbui templates are:
- **HTML-based**: Use web standards, not proprietary formats
- **Responsive**: Adapt to any screen size automatically
- **Accessible**: Built-in ARIA support and keyboard navigation
- **Themeable**: Complete separation of structure and style
- **Extensible**: Add your own components and behaviors
## Available Templates
Start with pre-built templates:
- `default.gbui` - Full-featured desktop interface
- `single.gbui` - Minimalist chat interface
- `mobile.gbui` - Touch-optimized experience
- `kiosk.gbui` - Public display mode
- `widget.gbui` - Embeddable component
## Integration Patterns
Learn to integrate with:
- Existing web applications
- Mobile apps via WebView
- Desktop applications
- Progressive Web Apps (PWA)
## Further Reading
- [UI Design Philosophy](/blog/no-forms)
- [Breaking Platform Lock-in](/blog/deswindonization)
- [Rich Interactions](/blog/beyond-chatbots)
Chapter 5: CSS Theming (gbtheme)
Related Blog Posts:
- "Deswindonization" - Visual independence
- "Breaking free from proprietary ecosystems"
Enhanced Introduction:
# Chapter 05: gbtheme CSS Reference
Great AI deserves great design. The .gbtheme system gives you complete control over your bot's visual identity without touching code. From corporate minimalism to playful personalities, your bot can look exactly how you envision.
## Visual Independence
Following our ["Deswindonization"](/blog/deswindonization) philosophy, themes aren't locked to any design system. Use Material Design, Bootstrap, or create something entirely unique. Your bot, your brand, your rules.
## Psychology of Design
Visual design affects user trust and engagement:
- **Professional themes** for enterprise deployments
- **Friendly themes** for customer service
- **Minimalist themes** for productivity tools
- **Playful themes** for educational bots
## Theme Architecture
Themes are just CSS - no proprietary formats:
- CSS custom properties for colors
- Flexible class targeting
- Media queries for responsive design
- Animation and transition support
- Dark mode variations
## Pre-Built Themes
Start with our curated themes:
- `default.css` - Clean, modern design
- `3dbevel.css` - Retro Windows 95 aesthetic
- `dark.css` - Eye-friendly dark mode
- `minimal.css` - Distraction-free
- `corporate.css` - Professional appearance
## Customization Workflow
1. Start with a base theme
2. Override CSS variables
3. Adjust component styles
4. Test across devices
5. Package and deploy
## Advanced Techniques
- Dynamic theme switching
- User preference persistence
- Seasonal variations
- A/B testing different designs
- Performance optimization
Chapter 6: BASIC Dialogs (gbdialog)
Related Blog Posts:
- "BASIC for Everyone" - Philosophy and accessibility
- "BASIC LLM Tools" - Extending LLMs with code
- "MCP is the new API" - Tool integration
Enhanced Introduction:
# Chapter 06: gbdialog BASIC Reference
BASIC is back, and it's powering the AI revolution. In an age of complex programming languages, General Bots chose BASIC for a simple reason: everyone can learn it in minutes, yet it's powerful enough to orchestrate sophisticated AI workflows.
## Why BASIC in 2025?
As detailed in ["BASIC for Everyone"](/blog/basic-for-everyone), we believe AI development shouldn't require a computer science degree. BASIC's English-like syntax means:
- Business analysts can write automation
- Teachers can create educational bots
- Doctors can build medical assistants
- No programming background needed
## Beyond Simple Scripts
Modern BASIC isn't your grandfather's language. ["BASIC LLM Tools"](/blog/basic-llm-tools) shows how BASIC scripts can:
- Orchestrate multiple AI models
- Process complex data
- Integrate with any API
- Handle enterprise workflows
- Scale to millions of users
## The MCP Revolution
["MCP is the new API"](/blog/mcp-is-the-new-api) explains how BASIC scripts can instantly become tool servers for any AI system. Write once in BASIC, use everywhere:
- As Claude MCP tools
- As OpenAI functions
- As REST APIs
- As automation scripts
## Core Concepts
BASIC in General Bots is:
- **Conversational**: TALK, HEAR, and natural flow
- **Integrated**: Direct access to AI, knowledge, and tools
- **Asynchronous**: Handle multiple conversations
- **Stateful**: Remember context across sessions
- **Extensible**: Add custom keywords easily
## Your First Script
```basic
' Greet the user
TALK "Hello! I'm your AI assistant."
' Get their name
TALK "What's your name?"
name = HEAR
' Personalized response
TALK "Nice to meet you, " + name + "!"
' Offer help
TALK "What can I help you with today?"
request = HEAR
' Use AI to help
response = LLM "Help the user with: " + request
TALK response
Power Features
Advanced capabilities you'll learn:
- Multi-channel messaging (WhatsApp, Teams, Email)
- Database operations
- File handling
- API integration
- Scheduled tasks
- Error handling
- User authentication
Success Stories
See BASIC in action:
- Customer service automation
- Data processing pipelines
- Report generation
- Appointment scheduling
- Content creation
Further Reading
### Chapter 7: Architecture (gbapp)
**Related Blog Posts:**
- "Why Pragmatismo Selected Open Source" - Architecture decisions
- "Cost-Effective Bot Orchestration" - System design
- "LLM Boom Is Over" - Practical architecture
**Enhanced Introduction:**
```markdown
# Chapter 07: gbapp Architecture Reference
Understanding General Bots' architecture empowers you to extend, optimize, and scale your AI infrastructure. Built on Rust for performance and reliability, the system is designed for both simplicity and power.
## Architectural Philosophy
As explained in ["Why We Selected Open Source"](/blog/why-pragmatismo-selected-open-source), every architectural decision prioritizes:
- **Ownership**: You control every component
- **Simplicity**: Single binary, minimal dependencies
- **Performance**: Rust's speed and safety
- **Flexibility**: Modular feature system
- **Scalability**: From laptop to cloud cluster
## The Post-Boom Architecture
["LLM Boom Is Over"](/blog/llm-boom-is-over) discusses the shift from hype to practical applications. General Bots' architecture reflects this maturity:
- Local-first design
- Efficient resource usage
- Practical feature set
- Production stability
## Cost-Effective Design
["Cost-Effective Bot Orchestration"](/blog/cost-effective-bot-orchestration) shows how architectural choices reduce costs:
- Single binary deployment
- Embedded databases option
- Efficient caching
- Minimal resource requirements
- Horizontal scaling capability
## System Components
Core architecture modules:
- **Bootstrap**: Zero-configuration setup
- **Package Manager**: Template system
- **Session Manager**: Conversation state
- **LLM Router**: Model orchestration
- **Storage Layer**: Files and data
- **Channel Adapters**: Multi-platform support
## Development Workflow
Extending General Bots:
1. Understanding the module structure
2. Adding custom keywords
3. Creating channel adapters
4. Building integrations
5. Contributing upstream
## Performance Characteristics
- Startup time: < 2 seconds
- Memory usage: ~100MB base
- Concurrent sessions: 10,000+
- Response latency: < 50ms
- Throughput: 1,000 msg/sec
## Further Reading
- [Architecture Decisions](/blog/why-pragmatismo-selected-open-source)
- [Practical AI Systems](/blog/llm-boom-is-over)
- [Cost Analysis](/blog/cost-effective-bot-orchestration)
Chapter 8: Configuration (gbot)
Related Blog Posts:
- "Own Your Authenticator Stack" - Security configuration
- "Marginalized E-mail Services" - Email setup challenges
- "SDG AI" - Configuring for social good
Chapter 9: API and Tools
Related Blog Posts:
- "MCP is the new API" - Modern tool integration
- "BASIC LLM Tools" - Tool creation patterns
- "Carl vs. Wilson" - API vendor lock-in
Chapter 10: Features
Related Blog Posts:
- "Digital Twins" - Advanced features
- "RCS vs. WhatsApp" - Channel comparison
- "Beyond Chatbots" - Feature possibilities
Chapter 11: Community
Related Blog Posts:
- "Carl vs. Wilson" - Open source benefits
- "Sustainable Development Goals and AI" - Community impact
- "Deswindonization" - Community philosophy
Implementation Strategy
1. Add Blog Links to Chapter Footers
Each chapter should include a "Further Reading" section with relevant blog posts:
## Further Reading
### Related Blog Posts
- [Title 1](/blog/slug-1) - Brief description
- [Title 2](/blog/slug-2) - Brief description
- [Title 3](/blog/slug-3) - Brief description
### Next Chapter
Continue to [Chapter Name](../chapter-XX/README.md)
2. Enhanced Chapter Introductions
Each main chapter README should include:
- Hook: Why this matters (2-3 sentences)
- Context: Connection to broader concepts
- Philosophy: Link to relevant blog posts
- What You'll Learn: Clear objectives
- Prerequisites: What to know first
- Real-World Applications: Concrete examples
- Further Reading: Blog posts for depth
3. Blog Post Updates
Add documentation links to relevant blog posts:
## Learn More
This concept is covered in depth in our documentation:
- [Chapter X: Topic Name](/docs/chapter-XX/) - Full technical reference
- [Quick Start Guide](/docs/chapter-01/quick-start) - Get started in 5 minutes
4. Cross-Reference Matrix
Create a matrix showing blog ↔ documentation relationships:
| Blog Post | Primary Chapter | Secondary Chapters |
|---|---|---|
| BASIC for Everyone | Ch 6: gbdialog | Ch 2: Packages |
| No Forms | Ch 4: .gbui | Ch 5: gbtheme |
| MCP is the new API | Ch 9: API | Ch 6: gbdialog |
| Digital Twins | Ch 2: Packages | Ch 10: Features |
| LLM Myths | Ch 3: gbkb | Ch 10: Features |
5. Educational Path Recommendations
Create learning paths that combine blog posts and documentation:
Path 1: Business User
- Blog: "No Forms"
- Blog: "BASIC for Everyone"
- Doc: Chapter 1 - Quick Start
- Doc: Chapter 6 - BASIC Basics
- Blog: "Ready-to-Use Templates"
Path 2: Developer
- Blog: "Why Open Source"
- Doc: Chapter 1 - Installation
- Doc: Chapter 7 - Architecture
- Blog: "MCP is the new API"
- Doc: Chapter 9 - API Reference
Path 3: Enterprise Architect
- Blog: "Cost-Effective Orchestration"
- Blog: "Own Your Stack"
- Doc: Chapter 7 - Architecture
- Doc: Chapter 12 - Security
- Blog: "Carl vs. Wilson"
Metrics for Success
Track engagement to optimize the integration:
- Click-through rate from docs to blog
- Click-through rate from blog to docs
- Time spent on enhanced introductions
- User journey completion rates
- Feedback on educational value
Next Steps
- Update all chapter README files with enhanced introductions
- Add "Further Reading" sections to each chapter
- Update blog posts with documentation links
- Create visual learning path diagram
- Add navigation hints in both blog and docs