diff --git a/docs.json b/docs.json index 2f4d0288a..ba738cec9 100644 --- a/docs.json +++ b/docs.json @@ -27,6 +27,7 @@ "pages": [ "index", "quickstart", + "non-technical-guide", "installation", "editor", "ai-native", diff --git a/non-technical-guide.mdx b/non-technical-guide.mdx new file mode 100644 index 000000000..98c78902b --- /dev/null +++ b/non-technical-guide.mdx @@ -0,0 +1,266 @@ +--- +title: "Mintlify for non-technical users" +description: "Create and manage beautiful documentation without coding experience." +keywords: ["non-technical", "beginner", "no code", "visual editor", "getting started"] +--- + +Mintlify makes it easy to create professional documentation without any coding knowledge. This guide walks you through everything you need to know to get started. + +## What is Mintlify? + +Mintlify is a platform for creating and hosting documentation websites. Think of it like a specialized website builder designed specifically for documentation—similar to how Squarespace or Wix work for regular websites, but optimized for technical content. + +You don't need to know how to code, use the command line, or understand technical concepts like Git to use Mintlify effectively. + +## Getting started + +### Create your account + +1. Visit [mintlify.com/start](https://mintlify.com/start) to create your account. +2. Follow the onboarding steps to set up your first documentation site. +3. After completing onboarding, your documentation site is automatically created and available at a URL like `https://your-project-name.mintlify.app`. + +You can find your site's URL on the Overview page of your [dashboard](https://dashboard.mintlify.com/). + +### Connect to GitHub + +Mintlify stores your documentation files on GitHub, a popular platform for storing and managing files. Don't worry—you don't need to learn how to use GitHub directly. Mintlify handles all the technical details for you. + +During onboarding, you'll be prompted to: +1. Create a GitHub account (if you don't have one). +2. Allow Mintlify to connect to your GitHub account. +3. Let Mintlify create a repository (a folder for your documentation files). + +This connection allows Mintlify to save your work and keep track of changes automatically. + +## Using the web editor + +The web editor is your main workspace for creating and editing documentation. It provides a visual interface where you can see your changes in real-time. + +### Access the editor + +1. Log in to your [dashboard](https://dashboard.mintlify.com). +2. Click **Editor** in the left sidebar. + + + The Mintlify web editor + The Mintlify web editor + + +### Navigate your documentation + +The left sidebar shows all your documentation files organized in folders. Click any file to open and edit it. + +Your documentation starts with a few default pages: +- **index.mdx**: Your homepage (the first page visitors see) +- **quickstart.mdx**: A getting started guide +- Additional pages depending on your template + +### Edit content + +Click any page in the sidebar to start editing. The editor works like a word processor with some special features: + +1. **Type naturally**: Just start typing to add or change text. +2. **Format text**: Use the toolbar to make text bold, italic, or create headings. +3. **Add components**: Type `/` to open a menu of special elements you can add: + - Code blocks for showing code examples + - Callout boxes to highlight important information + - Cards for organizing content visually + - Tabs for showing multiple options + - And many more + + + The editor shows you exactly how your documentation will look to visitors. What you see is what you get. + + +### Add images + +To add an image to your documentation: + +1. Click where you want the image to appear. +2. Type `/` and select **Image** from the menu. +3. Upload your image file or paste a URL. +4. Add a description (this helps with accessibility and search engines). + +### Create new pages + +To add a new page to your documentation: + +1. Click the **+** button next to the file list in the sidebar. +2. Choose **New page**. +3. Give your page a name and title. +4. Start adding content. + + + New pages are automatically saved but won't appear on your live site until you publish them. + + +### Organize pages + +You can organize your documentation into sections: + +1. Click the **+** button in the sidebar. +2. Choose **New folder** to create a section. +3. Drag and drop pages into folders to organize them. +4. Rename folders by right-clicking them. + +## Publishing your changes + +When you're happy with your edits, click the **Publish** button in the top-right corner. Your changes will be live on your documentation site within a few minutes. + + + Publishing is safe—you can always make more changes and publish again. Each publish creates a snapshot of your documentation that you can return to if needed. + + +## Customizing your site + +### Change colors and appearance + +1. Go to your [dashboard](https://dashboard.mintlify.com). +2. Click **Settings** in the left sidebar. +3. Select **Appearance** to customize: + - Your site's colors + - Logo and favicon (the small icon in browser tabs) + - Font choices + - Light and dark mode settings + +### Set up a custom domain + +Instead of using `your-project-name.mintlify.app`, you can use your own domain like `docs.yourcompany.com`: + +1. Go to **Settings** > **Domain** in your dashboard. +2. Enter your desired domain name. +3. Follow the instructions to update your domain settings with your domain provider. + + + If you're not familiar with domain settings, ask your IT team or domain provider for help with the DNS configuration step. + + +### Organize navigation + +Control how pages appear in your site's navigation menu: + +1. In the web editor, look for the **Navigation** panel. +2. Drag and drop pages to reorder them. +3. Create groups to organize related pages together. +4. Hide pages that you're not ready to show yet. + +## Getting help with AI + +Mintlify includes an AI assistant that can help you write and improve your documentation. + +### Use the agent + +Press +I (Mac) or Ctrl+I (Windows) to open the agent panel, or click the agent button in the top navigation. + +You can ask the agent to: +- Write new documentation pages +- Improve existing content +- Fix formatting issues +- Add components and examples +- Reorganize content + +For example, try asking: +- "Create a getting started guide for our API" +- "Add a troubleshooting section to this page" +- "Make this explanation simpler" + +The agent will make suggestions and create pull requests (proposed changes) that you can review before publishing. + +## Common tasks + +### Add a code example + +1. Type `/` and select **Code block**. +2. Choose the programming language. +3. Paste or type your code. +4. Add a title or description if needed. + +### Create a callout box + +Callout boxes highlight important information: + +1. Type `/` and select **Callout**. +2. Choose the type: + - **Note**: General information + - **Tip**: Helpful suggestions + - **Warning**: Important cautions + - **Info**: Additional context + +### Add a table + +1. Type `/` and select **Table**. +2. Choose the number of rows and columns. +3. Fill in your content. +4. Use the toolbar to add or remove rows and columns. + +### Embed a video + +1. Type `/` and select **Video** or **Frame**. +2. Paste the URL of your video (YouTube, Vimeo, etc.). +3. The video will be embedded directly in your documentation. + +## Tips for success + + + + Begin with just a few essential pages. You can always add more content later. Focus on what your users need most. + + + + Break up your content with descriptive headings. This makes it easier for readers to scan and find information. + + + + Screenshots, diagrams, and videos help explain complex concepts. A picture really is worth a thousand words. + + + + Always review your changes in the editor preview before publishing. Check for typos and make sure everything looks right. + + + + Set a regular schedule to review and update your documentation. Outdated documentation is worse than no documentation. + + + +## Getting help + +If you get stuck or have questions: + +- **Documentation**: Browse these docs for detailed guides and examples. +- **AI agent**: Ask the built-in AI assistant for help with specific tasks. +- **Support**: Contact Mintlify support through the dashboard. +- **Community**: Join the Mintlify community to connect with other users. + +## Next steps + +Now that you understand the basics, explore these topics to enhance your documentation: + + + + Learn about accordions, tabs, cards, and other components to make your docs more engaging. + + + + Make your documentation match your brand with custom colors and styling. + + + + Structure your documentation so users can easily find what they need. + + + + Discover how the AI assistant can help your users find answers quickly. + + + +Remember: You don't need to be technical to create great documentation. Focus on explaining things clearly, and Mintlify handles the rest.