Pular para o conteúdo principal

Beginners Guide

Doc-as-code is an approach where documentation is treated like software code. It involves writing, editing, and versioning documentation using the same tools and processes that developers use for coding. This method brings the benefits of collaboration, version control, and automation to documentation, making it easier to maintain high-quality and up-to-date content.

Doc-as-Code Using GitHub + VS Code​

In this guide, you'll learn how to start creating and collaborating on documentation using the doc-as-code approach with GitHub.

Requirements​

Before jumping into this guide, make sure that you have the following requirement checked:

  • GitHub account.
  • Completed the steps described on Quickstart at least until Step 3.

Step 1: Install GitHub Desktop​

GitHub Desktop is a user-friendly application that helps you interact with your GitHub repositories locally. To install GitHub Desktop:

  1. Visit the GitHub Desktop download page.
  2. Download and install the application for your operating system.
  3. Once installed, log in with your GitHub credentials.

Step 2: Install Visual Studio Code (VS Code)​

Visual Studio Code (VS Code) is a powerful and lightweight code editor that's ideal for editing Markdown files. To install VS Code:

  1. Visit the Visual Studio Code download page.
  2. Download and install the application for your operating system.
  3. After installation, open VS Code and install any relevant extensions for Markdown editing (e.g., "MDX" and "MDX Preview").

Step 3: Clone your documentation project​

To start working on the documentation project you created on the Quickstart, you'll need to clone the repository to your local machine:

  1. Open GitHub Desktop.
  2. Click on File > Clone repository.
  3. Choose documentation you created on the Quickstart.
  4. Select the local path where you want to save the repository and click Clone.

Step 4: Open the project in VS Code​

Once the repository is cloned, you can start editing the files:

  1. On GitHub Desktop, make sure that the repository showing on the top is your documentation repository.
  2. Click Open Visual Studio Code to open VS Code directly with your project.

Step 5: Edit the documentation files​

Now you're ready to start editing the documentation. Make a test editing an existing page:

  1. Navigate to the Markdown file you want to edit in the VS Code Explorer pane.
  2. Click on the file to open it in the editor.
  3. Make your changes using Markdown syntax.
WriteDocs Template

You will notice that on WriteDocs alreay provides some pages in our template so you can have a better understanding of how the MDX pages are organized.

Step 6: Commit your changes to GitHub​

After editing the files, you'll can to commit your changes and push them back to GitHub:

  1. Go back to GitHub Desktop.
  2. You'll see your changes listed in the Changes pane.
  3. Write a commit message describing your changes in the Summary field (optional).
  4. Click Commit to [branch name] to commit your changes.
  5. Click Push origin` to push your changes to the GitHub repository.

What's Next?​

Now that you already know how to edit pages and commit changes to GitHub, we recommend you to follow the sequence below to get the most of WriteDocs:

  1. Global Settings
  2. MDX Pages
  3. API Pages (if you need to create API docs)
  4. Components