a3943189ed
- Created new 'Contributing' section for developer-focused content - Moved installation instructions from guide/installation to contributing/ - Updated installation guide to use Taskfile commands instead of raw pnpm - Added comprehensive contributing guidelines including: - Development setup using task commands (setup:deps, docs:dev, etc.) - Project structure and workflow explanations - Contribution guidelines and review process - Development tips and testing procedures - Updated navigation to include Contributing as top-level item - Reorganized sidebar to remove installation from Getting Started - Updated main guide to focus on using documentation vs. contributing - Removed old guide/installation.md and empty guide/ directory New structure better separates: - Guide: For documentation users (how to find and use resources) - Contributing: For project contributors (how to develop and contribute) Task commands highlighted: - task setup:deps (install dependencies) - task docs:dev (development server) - task docs:build (build site) - task docs:preview (preview built site)
4.0 KiB
Getting Started with Awesome Docs
Welcome to Awesome Docs - your comprehensive guide to documentation tools, resources, and best practices!
What is Awesome Docs?
Awesome Docs is a curated collection of tools, resources, and guidelines for creating, maintaining, and improving documentation. Whether you're a developer, technical writer, or documentation maintainer, you'll find valuable resources here.
How to Use This Documentation
🔍 Finding What You Need
Use the Search Function
- Press
/orCtrl+Kto open search - Search for specific tools, technologies, or concepts
- Get instant results across all content
Browse by Category
- Tools: Explore documentation generators, API tools, and quality assurance utilities
- Resources: Access style guides, reading lists, and automation workflows
- Contributing: Learn how to contribute to this project
📚 Main Categories
Core Tools
- Site Generators - Static site generators for documentation (VitePress, Docusaurus, MkDocs, etc.)
- API Documentation - Tools for creating and maintaining API documentation (Swagger, ReDoc, etc.)
Content & Quality
- Writing Tools - Grammar checkers, style guides, and writing assistance
- Quality Assurance - Linting, testing, and validation tools for documentation
Resources & Learning
- Style Guides - Documentation and writing style guides from major organizations
- Reading List - Articles, tutorials, and best practices for documentation
- GitHub Actions - Automation workflows for documentation projects
Quick Recommendations
New to Documentation?
Start with these beginner-friendly tools:
- Docusaurus - Easy to set up, great for React projects
- VitePress - Fast and modern, perfect for Vue projects
- MkDocs - Simple and straightforward, great for Python projects
Looking for Specific Solutions?
API Documentation: Check out Swagger or ReDoc
Quality Assurance: Try Vale for style checking or Alex for inclusive language
Hosting: Consider Netlify, Vercel, or GitHub Pages
Documentation Best Practices
Planning Your Documentation
- Know Your Audience - Who will be reading your docs?
- Define Your Goals - What should users accomplish?
- Choose the Right Tools - Match tools to your team's skills and needs
- Plan Your Structure - Organize content logically
Creating Great Content
- Start with the User Journey - How do users discover and use your product?
- Use Clear, Simple Language - Avoid jargon and complex terminology
- Include Examples - Show, don't just tell
- Keep It Updated - Regular maintenance is essential
Tools and Workflows
- Version Control - Keep documentation in Git alongside code
- Automation - Use CI/CD for building and deploying docs
- Quality Checks - Implement linting and link checking
- Feedback Loops - Make it easy for users to provide feedback
Contributing to Awesome Docs
Want to help improve this resource? We welcome contributions!
- Add New Tools - Found a great documentation tool not listed here?
- Improve Existing Content - Help us keep information current and accurate
- Share Best Practices - Contribute your documentation experience
See our Contributing Guide for detailed instructions on how to get started.
Stay Updated
This is a living document that grows with the documentation community. Check back regularly for new tools, updated information, and fresh resources.
Found this helpful? Consider starring our GitHub repository and sharing it with your team!