This is the multi-page printable view of this section. .

Return to the regular view of this page.

Docs

Learn the project, install it, follow a tutorial, and look up exact behavior.

1: Introduction
- 1.1: Project Overview
- 1.2: Architecture
2: Get Started
- 2.1: Requirements
- 2.2: Installation
3: Tutorial
- 3.1: Make Your First Change
- 3.2: Add a Documentation Page
4: Reference
- 4.1: Configuration
- 4.2: Command Reference

The documentation follows four familiar paths: understand the project, get it running, learn by doing, then consult the reference.

1 - Introduction

Understand the project and the ideas behind it.

Start here when the project is new to you.

1.1 - Project Overview

State what the project does, who it serves, and why it exists.

Replace this page with the shortest useful explanation of your project.

The problem

Describe the problem in the reader’s language. Avoid implementation details until the reader understands why the project matters.

The outcome

Explain what a successful user can do after adopting the project.

Tip

A strong overview helps readers decide whether to continue in less than two minutes.

1.2 - Architecture

Give readers a stable mental model of the project.

Document the few components a contributor must understand before making a change.

System map

Part	Responsibility
Interface	Accepts user input and presents results
Core	Applies the project’s rules
Adapters	Connect external systems

Boundaries

Name what the project deliberately does not own. Clear boundaries prevent documentation from promising more than the software provides.

2 - Get Started

Check the prerequisites and complete a first installation.

Move from a clean machine to a working local result.

2.1 - Requirements

List the tools and access needed before installation.

Keep prerequisites short, exact, and testable.

Tools

A supported operating system.
Git for retrieving the source.
The runtime version required by your project.

Verify

Give readers one command per prerequisite:

$ project --version
project 0.1.0

Replace the placeholder command with your own before publishing.

2.2 - Installation

Take a new user from source code to a working result.

Show the shortest supported installation path first.

Install

git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
./project start

Confirm the result

Tell readers exactly what success looks like: a URL to open, a message to see, or a command whose exit status is zero.

Important

Replace every uppercase placeholder before publishing your project documentation.

3 - Tutorial

Learn the project by making a small, complete change.

Follow an end-to-end task instead of reading isolated facts.

3.1 - Make Your First Change

Complete one small change and verify it locally.

This sample tutorial models a complete task: prepare, change, verify, and review.

Start from a known state

git status --short
git switch -c docs/first-change

Change one thing

Edit a visible string or a small configuration value. Keep the first task narrow enough that its result is obvious.

Verify

Run the project’s smallest relevant check, then open the changed surface and inspect it yourself.

3.2 - Add a Documentation Page

Create a page, place it in the sidebar, and link to it.

In OINK, the content tree is the documentation sidebar. A new Markdown file becomes a new page.

Create the file

---
title: New capability
description: What the capability does.
weight: 30
---

Explain the capability here.

Save it as content/docs/reference/new-capability.md.

Add translations

Create new-capability.zh.md and new-capability.fr.md beside it. Keep explicit heading IDs aligned across languages.

Preview

Run hugo server, open the new page, and use the language switcher to inspect every translation.

4 - Reference

Look up configuration and commands without reading a tutorial.

Use this section when you already know what you need to find.

4.1 - Configuration

Record supported keys, defaults, and examples in one place.

Replace this small table with the public configuration surface of your project.

Key	Type	Default	Meaning
`listen`	string	`127.0.0.1:8080`	Address used by the local server
`log_level`	string	`info`	Minimum emitted log level
`read_only`	boolean	`false`	Disable operations that change state

Example

listen: 0.0.0.0:8080
log_level: debug
read_only: true

Document validation and precedence beside the keys, not in a separate hidden guide.

4.2 - Command Reference

List each command with its purpose, syntax, and exit behavior.

`project start`

Starts the local service.

project start [--config FILE] [--listen ADDRESS]

`project check`

Validates configuration without starting the service. Exit status 0 means valid; any non-zero status means the configuration must not be deployed.

project check [--config FILE]

Replace these placeholders with commands copied from your real CLI help output.