Day 7: Wikis & Documentation — 30 Days of GitLab DevOps

Documentation is a critical pillar of DevOps and software engineering. Without clear, structured, and up-to-date documentation, even the most elegant codebase becomes difficult to maintain, scale, or hand over to other engineers. This guide explores the differences between good and bad documentation, dives deep into the architecture of GitLab Wikis, covers advanced Markdown formatting, and provides a step-by-step hands-on guide to building a production-grade documentation suite for your projects.

1. The Anatomy of Good vs. Bad Documentation

In software engineering, documentation is often treated as an afterthought. However, poor documentation introduces significant friction, increases onboarding times, and leads to operational errors during incidents.

Bad Documentation vs. Good Documentation

The 5 Core Questions of Good Documentation

Every technical project documentation suite must answer five fundamental questions:

1. What is this project? (Project name, high-level overview, and business/technical purpose).
2. How do I set it up? (Prerequisites, dependencies, and local environment configuration).
3. How do I run it? (Build, execution, and verification commands).
4. How does it work? (System architecture, data flow, and component interactions).
5. What do I do when it breaks? (Troubleshooting guides, error codes, and recovery steps).

2. Deep Dive into GitLab Wikis

While a single README.md file is sufficient for small, single-purpose repositories, it quickly becomes messy and unmanageable for large-scale projects or microservice architectures. This is where GitLab Wikis come in.

What is a GitLab Wiki?

A GitLab Wiki is not just a rich-text editor on a web page; it is a separate Git repository dedicated entirely to documentation.

Because the Wiki is its own Git repository:

• Every page creation, edit, or deletion generates a Git commit.
• It maintains a complete version history of your documentation.
• Changes can be tracked, compared, and reverted to previous states.
• It supports collaborative editing by multiple team members without cluttering the main application codebase.

3. README vs. GitLab Wiki (When to Use What)

Choosing where to place your documentation depends on the size, complexity, and audience of your project.

4. Advanced Markdown for Technical Documentation

Markdown is the standard language for writing technical documentation. To make your documentation highly readable, you should use advanced Markdown features such as structured headers, syntax-highlighted code blocks, callouts, and tables.

Headers

Use headers hierarchically to structure your document. Never skip header levels (e.g., do not jump from # to ###).

# Project Name (H1)
## Section Title (H2)
### Subsection Title (H3)

Syntax-Highlighted Code Blocks

Always specify the language of your code blocks to enable syntax highlighting. This makes configuration files and scripts much easier to read.

```bash
# Clone the repository
git clone https://gitlab.com/your-org/your-project.git

# Navigate to the directory
cd your-project

### Highlighting Important Notes (Callouts)
To draw attention to critical warnings, prerequisites, or tips, use blockquotes combined with bold text and emojis.

```markdown
> ⚠️ **CRITICAL WARNING:** Do not run database migrations directly in production without taking a manual snapshot first.

Step-by-Step Instructions

Use ordered lists for sequential procedures to ensure users do not skip steps.

1. **Clone the Repository:** Download the source code locally.
2. **Build the Docker Image:** Run the local build script.
3. **Run the Container:** Spin up the application on port 8080.

Tabular Synthesis for Port Configurations

Tables are highly efficient for presenting structured metadata, such as network port configurations, environment variables, or API endpoints.

| Service Name | Default Port | Protocol | Description |
| :--- | :--- | :--- | :--- |
| Frontend Web | `80` / `443` | HTTP/HTTPS | Serves the static UI assets via Nginx |
| Backend API | `5000` | TCP | Flask/Python REST API service |
| Database | `5432` | TCP | PostgreSQL relational database |

5. Architecture Documentation & Visual Diagrams

Text alone is rarely enough to explain complex distributed systems. Visualizing your system architecture helps engineers quickly build a mental model of how data flows through your application.

The Flow of Data

A typical web application architecture can be visualized as a vertical flow:

User Browser
     |
     | sends HTTPS request
     v
Nginx Reverse Proxy (Port 443)
     |
     | forwards request to backend
     v
Application Server (Port 5000)
     |
     | queries/updates data
     v
PostgreSQL Database (Port 5432)

Recommended Diagramming Tools

To create professional architecture diagrams, consider the following tools:

• Draw.io (diagrams.net): Excellent for structured, formal system architecture diagrams.
• Excalidraw: Great for hand-drawn, whiteboard-style conceptual diagrams.
• Mermaid.js: Allows you to generate diagrams directly inside Markdown using code.
• AI Diagram Generators: Useful for rapidly bootstrapping initial layout structures.

6. Step-by-Step Hands-on: Creating the Wiki Structure

Let's build a complete, professional wiki structure inside a GitLab project.

Step 1: Navigate to the Wiki Section

1. Open your GitLab project.
2. On the left sidebar, navigate to Plan -> Wiki.
3. Click on Create your first page (or New page if pages already exist).

Step 2: Create the Home Page

The home page acts as the landing page and table of contents for your documentation.

• Title: home
• Content:

# Welcome to the Project Documentation Wiki

This wiki contains all the technical documentation, setup guides, and architectural designs for our application.

## 📖 Navigation Directory

* [🚀 Local Setup Guide](setup-guide)
* [🚢 Deployment Guide](deployment-guide)
* [🏗️ System Architecture](architecture-guide)
* [🛠️ Troubleshooting Runbook](troubleshooting-guide)

---

> 💡 **Note:** This wiki is version-controlled. If you make updates, please write descriptive commit messages.

Click Create page.

Step 3: Create the Setup Guide

This page explains how to get the application running on a local development machine.

1. Click New page.
2. Title: setup-guide
3. Content:

# Local Setup Guide

Follow these steps to configure and run the application on your local development machine.

## 📋 Prerequisites

Before starting, ensure you have the following tools installed:
* Docker (v20.10 or higher)
* Docker Compose (v2.0 or higher)
* Git

## 🛠️ Step-by-Step Installation

1. **Clone the Repository:**
   ```bash
   git clone https://gitlab.com/your-org/your-project.git
   cd your-project

2. Configure Environment Variables: Copy the template environment file and update the values:

   BASH

   Copy

   cp .env.example .env
   

3. Start the Application: Use Docker Compose to spin up the local environment:

   BASH

   Copy

   docker compose up -d --build
   

4. Verify the Installation: Open your browser and navigate to http://localhost:5000/health to verify the API is running.

Click **Create page**.

---

### Step 4: Create the Deployment Guide
This page outlines how the application is packaged and deployed to production environments.

1. Click **New page**.
2. **Title:** `deployment-guide`
3. **Content:**

```markdown
# Deployment Guide

This document describes the production deployment workflow and containerization strategy.

## 📦 Containerization

We package our application as a lightweight Docker image using a multi-stage build process.

### Production Dockerfile Example
```dockerfile
# Stage 1: Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Production stage
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

🚀 CI/CD Deployment Pipeline

Our deployments are automated via GitLab CI/CD. The pipeline executes the following stages:

Click **Create page**.

---

### Step 5: Create the Architecture Guide
This page details the system components and network configurations.

1. Click **New page**.
2. **Title:** `architecture-guide`
3. **Content:**

```markdown
# System Architecture Guide

This page details the system components, network architecture, and port mappings of our application.

## 🏗️ Component Architecture

Our system consists of three primary components:
1. **Frontend:** Static web assets served via Nginx.
2. **Backend API:** RESTful API handling business logic.
3. **Database:** Persistent storage layer.

## 🔌 Network & Port Configurations

The following ports must be open and configured in the security groups:

| Service | Internal Port | External Port | Protocol | Access Level |
| :--- | :--- | :--- | :--- | :--- |
| Nginx (Web) | `80` | `80` / `443` | TCP | Public |
| Backend API | `5000` | None | TCP | Internal Only |
| PostgreSQL | `5432` | None | TCP | Internal Only |

Click Create page.

Step 6: Create the Troubleshooting Guide

This runbook helps engineers diagnose and resolve common production issues.

1. Click New page.
2. Title: troubleshooting-guide
3. Content:

# Troubleshooting Runbook

Use this guide to diagnose and resolve common issues encountered during local development or production operations.

## 🔍 Common Issues and Solutions

### 1. Database Connection Refused
* **Symptom:** Backend logs show `Connection refused to host: localhost:5432`.
* **Reason:** The database container is either not running or has not finished initializing.
* **Resolution:**
  Verify the container status:
  ```bash
  docker ps -a | grep postgres

If it is stopped, restart it:

docker compose start db

2. Port 8080 Already in Use

• Symptom: Container fails to start with bind: address already in use.
• Resolution: Find the process using port 8080 and terminate it:
  BASH

  Copy

  sudo lsof -i :8080
  kill -9 <PID>
  

5. Write a descriptive commit message (e.g., docs: link README to project wiki pages).
6. Click Commit changes.

8. Version Control & History in GitLab Wikis

Because GitLab Wikis are backed by a standard Git repository, you have access to powerful version control features directly from the web interface.

Viewing Page History

1. Navigate to any Wiki page (e.g., setup-guide).
2. Click on the Page history tab at the top right of the page.
3. You will see a list of all revisions, including:
   • The author of the change.
   • The commit message.
   • The timestamp of the update.
   • The specific commit hash.

Revision 2 (Aditya - "docs: update docker compose commands") - 2 hours ago
   |
Revision 1 (Aditya - "docs: initial setup guide creation") - 1 day ago

Reverting Changes

If someone accidentally deletes important information or writes incorrect instructions:

1. Go to the Page history of that page.
2. Click on the specific commit version you wish to inspect.
3. Click the Revert button to roll back the wiki page to that exact point in time.

Summary and Key Takeaways

• Documentation is a Core DevOps Practice: High-quality documentation reduces onboarding friction, prevents operational mistakes, and ensures smooth handovers.
• GitLab Wikis are Git Repositories: Every wiki page is stored in a separate, dedicated Git repository, providing full version control, commit history, and rollback capabilities.
• Avoid README Bloat: Use the main project README.md as a high-level entry point, and offload complex, multi-page guides to the GitLab Wiki.
• Structure is Key: Good documentation must cover setup, usage, system architecture, and troubleshooting.
• Leverage Markdown Features: Use hierarchical headers, syntax-highlighted code blocks, tables, and callout blocks to make documentation readable and scannable.
• Visualize Architecture: Use simple, clean text flows or external diagramming tools (Draw.io, Excalidraw) to map out data flows and port configurations.
• Keep Docs Close to the Code: Link your main repository's README.md directly to your Wiki pages to create a seamless navigation experience for developers.