Documentation

Introduction

Good documentation is essential for projects to be successful. It allows team collaboration and easy onboarding, and preserves valuable knowledge.

GitLab offers a variety of powerful tools to help you document your project comprehensively.

In this guide, we will explore the different options available for project documentation.

By using these tools, you can create clear, accessible, and well-organized documentation.

GitLab Wiki

GitLab Wiki is an integrated feature within GitLab projects providing a collaborative space for teams to write, edit, and organize content.

It is a simple Markdown-based and lightweight markup language, making it easy to write and format documents.

In addition to Markdown, it also supports RDoc, AsciiDoc, and others. Choose what best suits your documentation needs.

Since it’s part of the GitLab project (behind the scene, GitLab wiki is simply a Git repository that can be cloned), all changes are versioned and can be traced back.

GitLab Wiki Facilitates team collaboration with easy access and edit permissions.

Wiki - Use Cases

• Internal Project Documentation: Best for internal documentation such as readme files, tutorials, how-to guides, and developer notes.
• Quick and Simple Documentation Needs: Ideal for projects requiring straightforward and easily accessible documentation.
• Collaborative Editing: Great for smaller teams or projects where multiple team members need to contribute to documentation regularly.
• Simplicity of usage: ideal for users unfamiliar with Git or when you want to quickly editing through GitLab’s interface.

The wiki’s simplicity is perfect for informal documentation. However, it can be a limitation if the content is critical, as you lose the advantages of the Git workflow (code review, validation, etc.).

GitLab Pages

GitLab Pages allows you to host static websites directly from documentation files stored in a GitLab repository.

Your documentation can be publicly accessible on the web through your custom domain.

GitLab CI/CD automates the building and deploymentof the site whenever changes are pushed to the repository. This ensures your site is always up-to-date with the latest content.

It also supports various static site generators like Hugo, Jekyll, and Docusaurus.

Pages - Use Cases

• Public Documentation Sites: Ideal for public-facing documentation like open-source project documentation, user manuals, and product documentation.
• Marketing and Portfolio Sites: Can be used to create marketing pages, personal portfolios, or company websites.
• Custom Layouts and Functionality: Suitable when you need advanced customization for the look and feel of your documentation or site.

In-Repository Documentation

Directly in the project’s repository, you can store documentation files (e.g., Markdown files like README.md, CONTRIBUTING.md, etc.).

Like the code, the documentation benefits from Git version control.

Use this for essential project documentation that stays alongside your code, like README, contributing guidelines, API documentation, changelogs, …

As a single-Source documentation, it helps to ensure that documentation is versioned and updated along with the code it relates to.

Readme Files

You can create README files in each repository, typically in Markdown format. Can be useful for providing a high-level overview of the project, installation instructions, quick start guides and basic usage information.

✅ To learn more on writing documentation, please visit our documentation practice pages