user-guides

name	user-guides
description	Create clear, comprehensive user guides and tutorials including step-by-step instructions, feature explanations, troubleshooting guides, and FAQ sections. Use this skill for documenting user workflows and creating tutorials.

User Guides & Tutorials Skill

Quick Start

User Guide Structure

# Getting Started with [Product]

## Overview
Brief (1-2 paragraph) explanation of what the product does and who it's for.

## System Requirements
- Minimum specifications
- Supported platforms
- Dependencies

## Installation

### Step 1: Download
Instructions with screenshots/links

### Step 2: Configure
Configuration steps with examples

### Step 3: Verify
How to confirm successful setup

## Basic Usage

### Your First Task
Step-by-step guide with:
- Clear numbered steps
- Screenshots at key points
- Expected results

### Common Actions
Table of frequent tasks with links

## Advanced Features

### Feature 1: Detail with Examples
Detailed explanation with code or configuration examples

## Troubleshooting

### Issue: [Common Problem]
**Symptom**: How to recognize this issue
**Cause**: Why it happens
**Solution**: Step-by-step fix

## FAQ

**Q: Common question?**
A: Clear, concise answer

## Next Steps
- Link to advanced tutorials
- Related features to explore
- Community resources

## Support
- Contact information
- Documentation links
- Community forums

Step-by-Step Tutorial Template

# Tutorial: [Specific Task]

## What You'll Learn
- Learning objective 1
- Learning objective 2
- Learning objective 3

## Prerequisites
- Required knowledge
- Required software/accounts
- Estimated time: 15 minutes

## Part 1: Understanding [Concept]

### 1.1 Key Concept Explanation
Paragraph with definition and context

### 1.2 Why This Matters
Explain practical applications

### 1.3 Example
Show real-world use case

## Part 2: Hands-On: [Specific Task]

### Step 1: Prepare Your Environment
\`\`\`bash
# Commands to run
command-here
\`\`\`

Expected output:
\`\`\`
Expected result shown here
\`\`\`

### Step 2: Create [Item]
Screenshot with annotation

Text explanation of what you did and why

### Step 3: Configure [Setting]
Detailed steps with:
- Navigation path: Menu > Submenu > Option
- Field values to enter
- Expected results

### Step 4: Test [Feature]
How to verify it works:
\`\`\`bash
# Test command
test-command
\`\`\`

✅ **Expected result**: Description of success

## Part 3: Common Variations

### Variation A: [Alternative Approach]
When to use and how it differs

### Variation B: [Another Option]
Additional context

## Troubleshooting This Tutorial

### Problem: [Issue]
- Check that X is set to Y
- Verify Z is installed
- Run this command to debug

## Congratulations!
Summary of what was accomplished

## Next Steps
- Link to related tutorials
- Advanced techniques
- Real-world applications

## Additional Resources
- Documentation links
- Code examples
- Community examples

Feature Explanation Format

# Feature: [Feature Name]

## What is it?
Clear, concise explanation (1-2 sentences)

## What problems does it solve?
- Problem 1
- Problem 2
- Problem 3

## How to Access
Navigation path with screenshots

## Basic Usage
Simple example showing core functionality

```javascript
// Simple example code
example-code-here

Advanced Usage

More complex scenarios with explanations

Common Use Cases

Use Case 1: [Specific Scenario]

When you'd use this feature and example

Use Case 2: [Another Scenario]

Example and explanation

Configuration Options

Option	Default	Description
option1	value1	Explanation
option2	value2	Explanation

Tips & Tricks

• Pro tip 1
• Pro tip 2
• Performance consideration

Limitations

Things it can't do or restrictions

Related Features

• Link to feature A
• Link to feature B

See Also

• Similar features
• Complementary tools

## Troubleshooting Guide Format

```markdown
# Troubleshooting Guide

## Before You Start
- Check system requirements
- Verify installation is complete
- Ensure you have admin access if needed

## Common Issues

### Issue 1: [Error Message or Symptom]

**Symptom:**
How to recognize this issue (error message, behavior, etc.)

**Likely Causes:**
1. Root cause A
2. Root cause B
3. Root cause C

**Solution:**
Follow these steps in order:

1. **Step 1**: Action with expected result
2. **Step 2**: Action with expected result
3. **Step 3**: Action with expected result

**Verify the fix:**
How to confirm it's working now

---

### Issue 2: [Another Common Problem]

**Symptom:**
Description

**Quick Fix:**
Try this first:
\`\`\`
code or command
\`\`\`

**If that doesn't work:**
More detailed troubleshooting steps

**Last Resort:**
Contact support with:
- System information
- Steps you've tried
- Error logs

## Still Having Issues?

### Gather Information
Run these commands to collect debug info:
\`\`\`bash
command-for-debug
\`\`\`

### Contact Support
Include:
- Debug information from above
- Steps to reproduce
- Screenshots/videos if applicable
- System details

### Community Resources
- GitHub Issues link
- Stack Overflow tag
- Community forum link

FAQ Template

# Frequently Asked Questions

## Getting Started

**Q: How do I install [Product]?**
A: [Link to installation guide] or [brief instructions]

**Q: What are the system requirements?**
A: [List requirements]

**Q: Is there a free trial?**
A: Yes/No. [Additional details]

## Usage

**Q: How do I do [Common Task]?**
A:
1. Step 1
2. Step 2
3. Step 3

[Link to detailed guide]

**Q: Can I do [Advanced Task]?**
A: Yes! [Brief explanation]. See [link to advanced guide] for details.

## Billing & Accounts

**Q: How does billing work?**
A: [Explanation of pricing model]

**Q: Can I upgrade/downgrade?**
A: [Explanation of how to change plans]

## Technical Issues

**Q: What should I do if I get [Error]?**
A: [Solution]. If that doesn't work, see [troubleshooting link].

**Q: Is [Issue] a known problem?**
A: [Status]. We're [working on it/released fix in version X]

## Integration & API

**Q: Can I integrate [Product] with [Service]?**
A: [Yes/No/Partially]. See [documentation link]

**Q: Is there an API?**
A: Yes! [Brief description]. Full docs: [API docs link]

## Billing & Support

**Q: How do I contact support?**
A:
- Email: [e-mail]
- Chat: [link]
- Status page: [link]

**Q: What's your support response time?**
A: [Typical SLA details]

## Not Seeing Your Question?

- [Search documentation link]
- [Community forum link]
- [Contact support link]

Best Practices

Writing for Users

✅ DO:

• Use simple, clear language
• Focus on what users want to do
• Include plenty of examples
• Provide screenshots for visual steps
• Use numbered lists for steps
• Include expected results
• Link related content
• Update regularly

❌ DON'T:

• Use technical jargon without explanation
• Write long paragraphs
• Assume user knowledge
• Skip error handling
• Use outdated screenshots
• Create dead links
• Overwhelm with options

Structure Guidelines

Heading Hierarchy:

• H1: Guide title
• H2: Major sections
• H3: Subsections
• H4: Details

Information Density:

• One concept per section
• 3-4 paragraphs max per section
• Use lists to break up text
• Include visual breaks

Screenshots & Visuals

1. Use high-quality screenshots
2. Add annotations/arrows pointing to relevant areas
3. Highlight fields users need to fill
4. Show both desktop and mobile if applicable
5. Update regularly when UI changes

Common Guide Patterns

Conceptual Guide

Explains "what is" and "why" without task focus

Task Guide

Step-by-step "how to" accomplish specific goal

Reference Guide

Complete list of options, parameters, features

Tutorial

Learning-focused, teaches concepts through practice

API Guide

Technical reference for developers

Tools for Creating Guides

Documentation Platforms

• Markdown-based: Notion, Coda, GitBook
• WYSIWYG: Confluence, Google Docs
• Static: MkDocs, Docusaurus, Hugo

Screenshot Tools

• Snagit, ShareX, Loom
• Browser extensions: Nimbus, Awesome Screenshot
• Built-in: macOS Screenshot, Windows Snip & Sketch

Formatting

• Markdown for simplicity
• HTML for control
• ReStructuredText for Sphinx

Next Steps

1. Choose guide type - Conceptual, task, or reference
2. Define audience - Beginner, intermediate, advanced
3. Outline structure - Use templates above
4. Write first draft - Focus on clarity over perfection
5. Add visuals - Screenshots and diagrams
6. Get feedback - Review with target users
7. Publish and maintain - Keep content fresh