Setting up a local environment

Whether you are a contributor or a GitLab Technical Writing team member, one of your first tasks is to set up an environment on your computer for writing and previewing GitLab documentation.

Tools for technical writers

You can use the following tools to set up your environment. Most of these are not compulsory - you can set up your environment however you choose. These are simply suggestions to help you get up and running quickly:

• If you haven’t already, install Git and add an SSH key to your GitLab profile. This step is required.
• Install a code editor, like VS Code or Sublime Text, where you will work with markdown files. You can use whichever tool you’re most comfortable with.
• Install documentation linters and configure them in your code editor:
  • markdownlint
  • Vale
• To build the docs site locally, install the requirements and dependencies. If you are new to working on GitLab documentation as a Technical Writing team member, getting this basic local build and preview setup is recommended. GDK can be added later, after you are comfortable using the combination of Git, text editor, linters, and Nanoc (static site generator) the Technical Writing workflow.
• Install the GitLab Development Kit (GDK). GDK enables you:
  • To install, run, and maintain an instance of GitLab locally.
  • To preview documentation changes locally.
  • To preview code changes locally.
• Optional. Install the Conventional Comments extension for Chrome. The plugin adds Conventional Comment buttons to GitLab comment fields. Learning about the Conventional Comments message format can help you write better, more actionable review comments - with or without the plugin.

Additional resources

• The Documentation Style Guide defines the standards for GitLab documentation, including grammar and formatting.
• The documentation testing page has important information about tests you should run to help ensure the quality of our documentation codebase.
• The documentation topic types define the structure for how content should be organized.