Overview

Welcome to the documentation guidelines for Go-Go-Golems libraries and tools! Great documentation isn't just about being technically accurate - it's about creating an engaging, enjoyable learning experience for developers. We believe that documentation should be both comprehensive and a pleasure to read, helping developers not just understand our libraries, but feel excited about using them.

This guide will walk you through our principles and practices for creating documentation that connects with readers while maintaining technical precision. Whether you're documenting a new feature or updating existing docs, these guidelines will help you create content that resonates with developers and makes their journey easier.

Document Structure

1. Frontmatter

Every document starts with YAML frontmatter that helps organize and categorize our content. Think of it as the metadata that helps developers find exactly what they need:

---
Title: Clear, Descriptive Title
Slug: url-friendly-identifier
Short: One-line description of the topic
Topics:
  - relevant
  - topic
  - tags
Commands:
  - RelatedCommands
Flags:
  - relevant-flags
IsTopLevel: true/false
ShowPerDefault: true/false
SectionType: GeneralTopic
---

2. Standard Sections

1. Overview Begin with a warm welcome that sets the stage for what readers will learn. Start with the essential details:

   • The package import path in backticks
   • An engaging description of what makes this library special
   • A simple import example to get started

   For example:

   import "github.com/go-go-golems/package/subpackage"
   

   📋

   Remember, this is your chance to get developers excited about what they're about to learn!

2. Table of Contents

   • List main sections in logical order
   • Use numbered list for easy reference

3. Core Concepts

   • Main types and interfaces
   • Key components
   • Architecture overview

4. Detailed Component Documentation

   • One section per major component
   • Include type definitions
   • Show usage examples

5. Examples

   • Start with simple cases
   • Progress to complex scenarios
   • Include complete, runnable code

6. Error Handling

   • Common error cases
   • How to handle errors
   • Debugging tips

Writing Style Guidelines

1. Voice and Tone

• Be Conversational: Write as if you're explaining concepts to a colleague over coffee. Use "you" and "we" to create connection.
• Stay Professional: While friendly, maintain technical accuracy and clarity.
• Show Enthusiasm: Let your excitement about the technology shine through!
• Use Active Voice: Instead of "The data is processed by the function", write "The function processes the data".

2. Structure and Flow

• Tell a Story: Lead readers from basic concepts to advanced features in a logical progression.
• Use Transitions: Help readers follow your thought process with clear connections between sections.
• Break Up Text: Use paragraphs, lists, and examples to make content digestible.
• Provide Context: Explain not just how, but why certain approaches are recommended.

3. Code Examples

Make your code examples tell a story too! Include narrative comments that explain the thinking behind the code:

import (
    "github.com/go-go-golems/package/subpackage"
    "github.com/go-go-golems/glazed/pkg/cmds"
)

func ExampleUsage() {
    // First, we create a new component with sensible defaults
    component, err := subpackage.NewComponent()
    if err != nil {
        // Always handle errors gracefully - your future self will thank you!
        return
    }

    // Now for the interesting part - let's transform some data
    result := component.DoSomething()
    
    // The result gives us exactly what we need for the next step
    // in our processing pipeline
}

2. Type Definitions

• Show complete struct definitions with tags
• Include field descriptions
• Document unexported fields if relevant

type Configuration struct {
    // Name is the identifier for this configuration
    Name string `yaml:"name" json:"name"`
    
    // unexported but important for understanding
    internal bool
}

3. Interface Definitions

• Document each method
• Include usage examples
• Show common implementations

// Processor handles data transformation
type Processor interface {
    // Process transforms input data according to configuration
    Process(ctx context.Context, data []byte) ([]byte, error)
}

Content Guidelines

1. Package References

• Always use full import paths in backticks
• Reference types with package prefix
• Link to related packages when relevant

Example:

• Package: github.com/go-go-golems/clay/pkg/sql
• Type: sql.Configuration
• Related: See also github.com/go-go-golems/glazed/pkg/cmds

2. Configuration Examples

• Show both YAML and Go representations
• Include all common options
• Explain each field's purpose

name: example-config
settings:
  timeout: 30s
  retries: 3

config := &Config{
    Name: "example-config",
    Settings: Settings{
        Timeout: 30 * time.Second,
        Retries: 3,
    },
}

3. Command-Line Integration

• Show Cobra integration when applicable
• Include flag definitions
• Demonstrate middleware usage

4. Error Messages

• List common error messages
• Explain causes and solutions
• Show error handling patterns

Documentation Types

1. Package Documentation

• Focus on API and usage
• Include package-level examples
• Document exported types and functions

2. Command Documentation

• Focus on user perspective
• Include CLI examples
• Show configuration options

3. Tutorial Documentation

• Step-by-step instructions
• Complete working examples
• Common use cases

Best Practices

1. Completeness

   • Document all major features
   • Include error handling
   • Show real-world examples

2. Clarity

   • Use consistent terminology
   • Explain complex concepts
   • Break down long examples

3. Maintainability

   • Keep examples up to date
   • Use version-specific notes
   • Link to related documentation

4. Accessibility

   • Use clear language
   • Provide context
   • Include troubleshooting tips

Example Documentation Structure

Here's a template that showcases our engaging documentation style:

---
Title: Working with Widgets - A Developer's Guide
Slug: widget-guide
Short: Master the art of widget manipulation in your applications
---

## Welcome to the World of Widgets!

Ever wondered how to make your application's widgets dance? The `github.com/organization/widgets` 
package is your backstage pass to creating dynamic, responsive widget experiences. Let's dive 
into what makes this package special and how you can harness its power in your applications.

## Getting Started

First things first - let's bring widgets into your project:

```go
import "github.com/organization/widgets"

The Widget Ecosystem

At the heart of our widget world lies the Widget type. Think of it as your Swiss Army knife for UI manipulation - it's flexible, powerful, and surprisingly easy to use:

type Widget struct {
    // These fields are your control panel for widget behavior
    Name        string
    Properties  map[string]interface{}
}

Creating Your First Widget

Let's create something magical together. Here's how you can bring a widget to life:

widget := widgets.NewWidget("my-first-widget")
// Now we have a widget ready to amaze users!

Best Practices

We've learned a few things on our widget journey. Here are some golden rules that will help you create exceptional widget experiences:

1. Always give your widgets meaningful names - they're not just identifiers, they're the building blocks of your user interface.
2. Keep widget properties focused and purposeful - resist the urge to create a "kitchen sink" widget.

Troubleshooting

Even the best widget wizards run into challenges sometimes. Here's how to handle common situations with grace and style...

## Conclusion

Remember, great documentation is your chance to have a conversation with developers who use our libraries. By combining technical precision with engaging, human-friendly writing, we create documentation that not only informs but inspires. Let's make learning about Go-Go-Golems libraries an enjoyable journey for everyone!