diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 3fc3bc1..174dfb7 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -30,8 +30,22 @@ export default defineConfig({ }, nav: [ { text: 'Home', link: '/' }, - { text: 'Guide', link: '/guide' }, - { text: 'API', link: '/api' } + { text: 'Tools', + items: [ + { text: 'Site Generators', link: '/generators' }, + { text: 'API Documentation', link: '/api' }, + { text: 'Quality Assurance', link: '/quality' }, + { text: 'Writing Tools', link: '/writing' } + ] + }, + { text: 'Resources', + items: [ + { text: 'Style Guides', link: '/style-guides' }, + { text: 'Reading List', link: '/reading' }, + { text: 'GitHub Actions', link: '/github-actions' } + ] + }, + { text: 'Guide', link: '/guide' } ], sidebar: [ { @@ -42,9 +56,25 @@ export default defineConfig({ ] }, { - text: 'Reference', + text: 'Core Tools', items: [ - { text: 'API Reference', link: '/api' } + { text: 'Site Generators', link: '/generators' }, + { text: 'API Documentation', link: '/api' } + ] + }, + { + text: 'Content & Quality', + items: [ + { text: 'Writing Tools', link: '/writing' }, + { text: 'Quality Assurance', link: '/quality' } + ] + }, + { + text: 'Resources', + items: [ + { text: 'Style Guides', link: '/style-guides' }, + { text: 'Reading List', link: '/reading' }, + { text: 'GitHub Actions', link: '/github-actions' } ] } ], diff --git a/docs/api.md b/docs/api.md index 32677c6..b26b838 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,81 +1,50 @@ -# API Reference +# API Documentation -This page contains the API reference for our documentation system. +Tools and resources for creating, testing, and maintaining API documentation. -## Configuration +## Documentation Generators -### Basic Configuration +### Interactive Documentation +- [Swagger](https://swagger.io/) - Industry standard for API documentation +- [ReDoc](https://redocly.github.io/redoc/) - Beautiful API documentation from OpenAPI +- [RapiDoc](https://mrin9.github.io/RapiDoc/index.html) - Custom element for OpenAPI docs +- [Bump.sh](https://bump.sh/) - API documentation platform with automated updates -The basic configuration includes: +### API Design Tools +- [Stoplight Studio](https://stoplight.io/studio/) - Visual API design editor +- [Postman](https://www.getpostman.com/) - API development environment +- [Hoppscotch](https://github.com/hoppscotch/hoppscotch) - Open source API development -- **Title**: Set the main title of your documentation -- **Description**: Provide a brief description -- **Theme**: Configure the appearance and behavior +## Testing & Validation -### Advanced Configuration +### Linting & Quality +- [Spectral](https://stoplight.io/open-source/spectral/) - JSON/YAML linter with OpenAPI rules +- [OpenAPI 3 CLI](https://github.com/Redocly/openapi-cli) - Command line tools for OpenAPI +- [Speccy](https://github.com/wework/speccy) - OpenAPI specification linter -For advanced users, you can customize: +### API Testing +- [Optic](https://www.useoptic.com/) - API change detection and testing +- [Restish](https://rest.sh/#/) - CLI for interacting with REST APIs -- **Navigation**: Custom navigation menus -- **Sidebar**: Dynamic sidebar generation -- **Search**: Local search configuration -- **Plugins**: Additional functionality +## Best Practices -## Methods +### Structure Your API Docs +1. **Overview** - What does your API do? +2. **Authentication** - How to authenticate requests +3. **Endpoints** - Available endpoints with examples +4. **Data Models** - Request/response schemas +5. **Error Handling** - Error codes and messages -### `configure(options)` +### Tips for Better Documentation +- Use real examples in your API documentation +- Include interactive testing capabilities +- Document error scenarios thoroughly +- Provide code samples in multiple languages +- Keep documentation in sync with API changes -Configure the documentation system with the provided options. +## Guidelines & Resources -**Parameters:** -- `options` (Object): Configuration options - - `title` (String): Documentation title - - `description` (String): Site description - - `theme` (Object): Theme configuration - -**Example:** -```javascript -configure({ - title: 'My Docs', - description: 'Comprehensive documentation', - theme: { - nav: [...], - sidebar: [...] - } -}) -``` - -### `search(query)` - -Perform a search across all documentation content. - -**Parameters:** -- `query` (String): Search query string - -**Returns:** -- Array of search results with matches - -## Examples - -Here are some common usage examples: - -### Setting up Navigation - -```javascript -nav: [ - { text: 'Home', link: '/' }, - { text: 'Guide', link: '/guide' }, - { text: 'API', link: '/api' } -] -``` - -### Configuring Search - -```javascript -search: { - provider: 'local', - options: { - // Search configuration - } -} -``` \ No newline at end of file +- [API Guidelines](https://dret.github.io/guidelines/) - Collection of API design guidelines +- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/#) - Comprehensive REST API guidelines +- [API Handyman](https://apihandyman.io/) - API design and documentation blog +- [Tips for better documentation with OpenAPI](https://lornajane.net/posts/2023/tips-for-better-documentation-with-openapi) \ No newline at end of file diff --git a/docs/generators.md b/docs/generators.md new file mode 100644 index 0000000..73b1736 --- /dev/null +++ b/docs/generators.md @@ -0,0 +1,128 @@ +# Site Generators + +Static site generators specifically designed for documentation, offering features like themes, plugins, and optimized workflows for technical content. + +## Popular Documentation Generators + +### VitePress +- **Website**: [vitepress.dev](https://vitepress.dev/) +- **Description**: Vue-powered static site generator, fast and modern +- **Best for**: Vue.js projects, modern documentation sites + +### Docusaurus +- **Website**: [docusaurus.io](https://docusaurus.io/) +- **Description**: React-based documentation platform by Meta +- **Best for**: React projects, large documentation sites + +### MkDocs +- **Website**: [mkdocs.org](https://www.mkdocs.org/) +- **Description**: Python-based static site generator +- **Best for**: Python projects, simple setup + +### GitBook +- **Website**: [gitbook.com](https://www.gitbook.com/) +- **Description**: Modern documentation platform with collaborative features +- **Best for**: Team collaboration, internal documentation + +## Framework-Specific Generators + +### Astro +- **Website**: [astro.build](https://astro.build/) +- **Extensions**: [Starlight](https://starlight.astro.build/) - Documentation theme +- **Best for**: Performance-focused sites, multi-framework support + +### Next.js +- **Website**: [nextra.site](https://nextra.site/) +- **Description**: Simple, powerful and flexible site generation framework +- **Best for**: React/Next.js projects + +### Nuxt.js +- **Website**: [docus.dev](https://docus.dev/) +- **Description**: Write docs with MDX and deploy with Nuxt +- **Best for**: Vue/Nuxt projects + +## Language-Specific Generators + +### Rust +- **Tool**: [mdBook](https://github.com/rust-lang/mdBook) +- **Description**: Command line tool to create books with Markdown files +- **Best for**: Rust projects, book-style documentation + +### .NET +- **Tool**: [DocFX](https://dotnet.github.io/docfx/) +- **Description**: Static documentation generator for .NET +- **Best for**: .NET projects, API documentation + +### Python +- **Tool**: [Sphinx](https://www.sphinx-doc.org/en/master/) +- **Description**: Documentation generator with powerful extensions +- **Best for**: Python projects, complex documentation + +## Lightweight & Simple + +### Docsify +- **Website**: [docsify.js.org](https://docsify.js.org/) +- **Description**: Magical documentation site generator without build process +- **Best for**: Simple sites, no build step required + +### 11ty +- **Website**: [11ty.dev](https://www.11ty.dev/) +- **Description**: Simple static site generator with multiple template languages +- **Best for**: Flexibility, custom designs + +### Zola +- **Website**: [getzola.org](https://www.getzola.org/) +- **Description**: Fast static site generator written in Rust +- **Best for**: Performance, simplicity + +## Specialized Solutions + +### Antora +- **Website**: [antora.org](https://antora.org/) +- **Description**: Multi-repository documentation site generator +- **Best for**: Large organizations, multiple repositories + +### Quartz +- **Website**: [quartz.jzhao.xyz](https://quartz.jzhao.xyz/) +- **Description**: Transform your Obsidian vault into a website +- **Best for**: Knowledge management, Obsidian users + +### Log4brains +- **Website**: [log4brains.org](https://log4brains.org/) +- **Description**: Documentation of architecture decision records (ADRs) +- **Best for**: Architecture decisions, ADR documentation + +## Extensions & Themes + +### Docsify Extensions +- [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/#/) - Themeable extension + +### MkDocs Extensions +- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - Material Design theme +- [Tooltipster Links Plugin](https://github.com/midnightprioriem/mkdocs-tooltipster-links-plugin) - Enhanced tooltips + +### Sphinx Extensions +- [MyST](https://myst-parser.readthedocs.io/en/latest/using/intro.html) - Markdown parser +- [sphinx-design](https://sphinx-design.readthedocs.io/en/latest/) - UI components +- [Furo](https://github.com/pradyunsg/furo) - Clean theme + +## Search Solutions +- [Meilisearch](https://www.meilisearch.com/) - Fast, typo-tolerant search +- [pagefind](https://pagefind.app/) - Static search for static sites +- [Typesense](https://typesense.org/) - Open source search engine + +## Choosing the Right Generator + +### Consider These Factors: +1. **Team Skills** - What languages/frameworks does your team know? +2. **Project Size** - Single repo vs. multi-repo documentation? +3. **Customization** - How much design flexibility do you need? +4. **Performance** - How fast does the site need to be? +5. **Maintenance** - How much ongoing maintenance can you handle? + +### Quick Recommendations: +- **New to docs**: Start with Docusaurus or VitePress +- **Python team**: Use MkDocs or Sphinx +- **Performance focus**: Try Astro or Zola +- **Simple needs**: Consider Docsify or 11ty +- **Large organization**: Look at Antora or GitBook \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 882700e..356a4a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,28 +1,45 @@ # Awesome Docs -Welcome to Awesome Docs! This is your home page. +[![Awesome](https://awesome.re/badge-flat2.svg)](https://awesome.re) -## What is this? +A **curated list** of awesome documentation tools, guides and best practices for creating, maintaining, and improving documentation. -This is a documentation site built with VitePress, a fast static site generator powered by Vite and Vue. +*If you see a package or project here that is no longer maintained or is not a good fit, please submit a pull request to improve this file. Thank you!* -## Quick Start +## 🚀 Quick Start -To get started with this documentation: +- **Browse by Category**: Use the navigation menu to explore specific tool categories +- **Search**: Use the search function to find specific tools or topics +- **Contributing**: Check our [contribution guidelines](https://github.com/testthedocs/awesome-docs/blob/master/CONTRIBUTING.md) -1. [Read the Guide](/guide) -2. [Learn about Installation](/guide/installation) +## 📋 Categories Overview -## Features +### 🛠️ Core Tools +- [Site Generators](./generators/) - Static site generators for documentation +- [API Documentation](./api/) - Tools for API documentation and testing +- [Editors](./editors/) - Markdown and documentation editors -::: info -VitePress provides many great features out of the box including: -- ⚡️ Fast hot reload -- 📝 Markdown-based content -- 🎨 Vue-powered theming -- 🔍 Built-in search -::: +### 🎨 Content Creation +- [Writing Tools](./writing/) - Grammar, style, and writing assistance +- [Visual Tools](./visual/) - Screenshots, screencasts, and mockups +- [Quality Assurance](./quality/) - Linting, testing, and validation -## Getting Help +### 🌐 Publishing & Hosting +- [Hosting Platforms](./hosting/) - Places to host your documentation +- [GitHub Actions](./github-actions/) - Automation for documentation workflows +- [Analytics](./analytics/) - Understanding your documentation usage -If you need help, please check out our [GitHub repository](https://github.com/testthedocs/awesome-docs). \ No newline at end of file +### � Learning Resources +- [Style Guides](./style-guides/) - Documentation and writing style guides +- [Reading List](./reading/) - Articles and resources about documentation +- [Best Practices](./best-practices/) - Proven strategies and approaches + +## 🤝 Contributing + +We welcome contributions! Please see our [contribution guidelines](https://github.com/testthedocs/awesome-docs/blob/master/CONTRIBUTING.md) for details. + +Thanks to all [contributors](https://github.com/testthedocs/awesome-docs/graphs/contributors) - you rock! 🎉 + +## 📄 License + +This project is licensed under [CC0 1.0 Universal](https://github.com/testthedocs/awesome-docs/blob/master/LICENSE). \ No newline at end of file diff --git a/docs/quality.md b/docs/quality.md new file mode 100644 index 0000000..90264a6 --- /dev/null +++ b/docs/quality.md @@ -0,0 +1,80 @@ +# Quality Assurance + +Tools and practices for ensuring documentation quality, accuracy, and consistency. + +## Language & Style Tools + +### Grammar & Writing +- [Alex](https://github.com/get-alex/alex) - Catch insensitive, inconsiderate writing +- [Harper](https://writewithharper.com/) - Grammar checker for developers +- [Vale](https://vale.sh/) - Syntax-aware linter for prose +- [Woke](https://getwoke.tech/) - Detect non-inclusive language + +### Style Consistency +- [case-police](https://github.com/antfu/case-police) - Make casing consistent +- [Capitalize My Title](https://capitalizemytitle.com/) - Title case formatter + +## Link & Content Validation + +### Link Checking +- [lychee](https://github.com/lycheeverse/lychee) - Fast link checker written in Rust +- [Linkspector](https://github.com/UmbrellaDocs/linkspector) - Web crawler for broken links +- [HtmlTest](https://github.com/wjdp/htmltest) - HTML validation and link checking +- [brok](https://github.com/smallhadroncollider/brok) - Find broken links in text files + +### Content Testing +- [Doc Detective](https://github.com/doc-detective/doc-detective) - Test documentation accuracy +- [Swimm](https://swimm.io/) - Keep code documentation synchronized + +## Accessibility & Readability + +### Accessibility Testing +- [AXE-CLI](https://github.com/dequelabs/axe-cli) - Accessibility testing from command line +- [Pa11y](https://pa11y.org/) - Automated accessibility testing +- [Lumberjack](https://github.com/JakePartusch/lumberjack) - Accessibility checker + +### Readability Analysis +- [Readable](https://www.webfx.com/tools/read-able/) - Readability score calculator +- [Contrastchecker](https://webaim.org/resources/contrastchecker/) - Color contrast validation + +## Automation & CI/CD + +### Automated Testing +- [Your automated tester](https://squidler.io/) - Documentation testing platform +- [InnovationEngine](https://github.com/Azure/InnovationEngine) - Content analysis and suggestions + +## Quality Assurance Workflow + +### Pre-Publishing Checklist +1. **Grammar & Style** - Run through Alex, Vale, or similar tools +2. **Link Validation** - Check all internal and external links +3. **Accessibility** - Ensure content meets accessibility standards +4. **Readability** - Verify content is appropriate for target audience +5. **Consistency** - Check terminology and formatting consistency + +### Continuous Quality +- Set up automated checks in CI/CD pipeline +- Regular link validation schedules +- Style guide enforcement +- User feedback integration + +### Tools Integration +Most quality assurance tools can be integrated into: +- **Git Hooks** - Run checks before commits +- **CI/CD Pipelines** - Automated quality gates +- **Editor Extensions** - Real-time feedback +- **GitHub Actions** - Automated PR checks + +## Best Practices + +### Establish Standards +- Create and maintain a style guide +- Define quality metrics and thresholds +- Document review processes +- Train team members on tools and standards + +### Monitor Continuously +- Regular audits of documentation quality +- Track metrics over time +- User feedback analysis +- Tool effectiveness evaluation \ No newline at end of file