markdown-documentation

# Markdown Documentation

Best practices for writing effective technical documentation in markdown.

## README Structure

### Minimal README

```markdown
# Project Name

Brief description of what this project does.

## Installation

Instructions to install.

## Usage

Basic usage example.

## License

MIT
```

### Comprehensive README

```markdown
# Project Name

![Build Status](badge-url)
![Version](badge-url)

One-paragraph description of the project.

## Features

- Feature one
- Feature two
- Feature three

## Installation

### Prerequisites

- Requirement 1
- Requirement 2

### Steps

Instructions...

## Usage

### Basic Example

Code example...

### Advanced Usage

More examples...

## Configuration

Configuration options...

## API Reference

API documentation...

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT License - see [LICENSE](LICENSE)
```

## Document Organization

### File Naming

```
docs/
├── README.md           # Entry point
├── CONTRIBUTING.md     # Contribution guidelines
├── CHANGELOG.md        # Version history
├── CODE_OF_CONDUCT.md  # Community guidelines
├── getting-started.md  # Onboarding guide
├── api/
│   ├── README.md       # API overview
│   └── endpoints.md    # Endpoint reference
└── guides/
    ├── installation.md
    └── configuration.md
```

### Linking Between Documents

```markdown
See the [installation guide](./guides/installation.md) for details.

For API reference, check [endpoints](./api/endpoints.md#authentication).
```

## Writing Style

### Be Concise

```markdown
<!-- Bad -->
In order to install the application, you will need to run the following command.

<!-- Good -->
Install the application:
```

### Use Active Voice

```markdown
<!-- Bad -->
The configuration file should be created in the home directory.

<!-- Good -->
Create the configuration file in your home directory.
```

### Address the Reader

```markdown
<!-- Bad -->
Users can configure the timeout setting.

<!-- Good -->
You can co