mirror of
https://github.com/testthedocs/awesome-docs.git
synced 2026-07-17 06:42:21 -05:00
d2eb3c152e
Move topic pages to section index routes, standardize card-based content presentation, and simplify metadata typing while improving local search indexing for EnhancedLink entries. Refresh theme styling and replace unstable external links to keep metadata builds reliable.
89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# 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 `/` or `Ctrl+K` to 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](/generators/)** - Static site generators for documentation (VitePress, Docusaurus, MkDocs, etc.)
|
|
- **[API Documentation](/api/)** - Tools for creating and maintaining API documentation (Swagger, ReDoc, etc.)
|
|
|
|
#### Content & Quality
|
|
- **[Writing Tools](/writing/)** - Grammar checkers, style guides, and writing assistance
|
|
- **[Quality Assurance](/quality/)** - Linting, testing, and validation tools for documentation
|
|
|
|
#### Resources & Learning
|
|
- **[Style Guides](/style-guides/)** - Documentation and writing style guides from major organizations
|
|
- **[Reading List](/reading/)** - Articles, tutorials, and best practices for documentation
|
|
- **[GitHub Actions](/github-actions)** - Automation workflows for documentation projects
|
|
|
|
## Quick Recommendations
|
|
|
|
### New to Documentation?
|
|
Start with these beginner-friendly tools:
|
|
- **[Docusaurus](https://docusaurus.io/)** - Easy to set up, great for React projects
|
|
- **[VitePress](https://vitepress.dev/)** - Fast and modern, perfect for Vue projects
|
|
- **[MkDocs](https://www.mkdocs.org/)** - Simple and straightforward, great for Python projects
|
|
|
|
### Looking for Specific Solutions?
|
|
|
|
**API Documentation**: Check out [Swagger](https://swagger.io/) or [ReDoc](https://redocly.github.io/redoc/)
|
|
|
|
**Quality Assurance**: Try [Vale](https://vale.sh/) for style checking or [Alex](https://github.com/get-alex/alex) for inclusive language
|
|
|
|
**Hosting**: Consider [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), or [GitHub Pages](https://pages.github.com/)
|
|
|
|
## Documentation Best Practices
|
|
|
|
### Planning Your Documentation
|
|
1. **Know Your Audience** - Who will be reading your docs?
|
|
2. **Define Your Goals** - What should users accomplish?
|
|
3. **Choose the Right Tools** - Match tools to your team's skills and needs
|
|
4. **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](/contributing/) 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](https://github.com/testthedocs/awesome-docs) and sharing it with your team!
|