What is Developer Docs

developer-docs is an open-source documentation project that provides guidelines and resources for developers. It is currently under construction, and contributions are welcomed.

Use cases

Use cases include creating developer guides, API documentation, and instructional materials that require visual elements like SVG graphics.

How to use

To use developer-docs, refer to the official website for the most up-to-date documentation. When incorporating SVG files in MDX files, ensure to use the ‘.url’ property to avoid build failures.

Key features

Key features include open-source accessibility, community contributions, and specific guidelines for using SVG files in documentation.

Where to use

developer-docs can be used in software development projects, technical documentation, and any context where clear and structured documentation is required.

Contributing to Speakeasy Documentation

Welcome to the Speakeasy documentation repository! This guide will help you contribute to our open-source documentation.

📂 Repository Structure

The documentation is organized into several content hubs:

• api-design/ - API design guidelines and best practices
• docs/ - Core product documentation
• guides/ - Step-by-step product guides
• mcp/ - MCP hub
• openapi/ - OpenAPI hub

✍️ How to Edit Content

1. Locate the File

The documentation files in this repository directly map to the URLs on our website. To find the file you want to edit:

1. Take the URL path after speakeasy.com/
2. Add .mdx to the end
3. That’s your file path in the repository

For example:

• Website URL: https://www.speakeasy.com/docs/prep-openapi/linting
  • File path: docs/prep-openapi/linting.mdx

2. Make Your Changes

• Use MDX (.mdx) when you need React components, or Markdown (.md) for simple content
• Follow our quick style guide below
• Include proper meta descriptions for SEO
• Optimize images using Next.js Image component

3. Submit Your Changes

1. Create a new branch for your changes
2. Commit with a descriptive message following Conventional Commits
   • Example: chore: update authentication guide
3. Create a pull request
4. Once approved, your changes will be merged

📝 Quick Style Guide

Writing Style

• Use clear, concise language
• Write in active voice
• Keep explanations brief and direct
• Use American English

Code and Links

• Use code blocks for code snippets
• Add language specification to code blocks
• Use relative URLs: [link](https://raw.githubusercontent.com/speakeasy-api/developer-docs/master//docs/create-client-sdks)
• Place code references in backticks

Formatting

• Use sentence case for headings
• Use proper heading hierarchy
• Include code examples where relevant
• Add proper meta descriptions for SEO

🚀 Getting Started

1. Fork the repository

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/developer-docs.git
   

3. Create a new branch:

   git checkout -b docs/your-change
   

4. Make your changes

5. Submit a pull request

🤝 Need Help?

• Open an issue for general questions
• Join our Slack community for real-time help
• Check existing issues and pull requests for similar questions

Thank you for contributing to our documentation! Your help makes our documentation better for everyone.