ブログに戻る
ドキュメント14 min read
Markdownドキュメントガイド：開発者のためのベストプラクティス
明確で保守可能なドキュメント作成のためのMarkdownをマスター。基本構文からプロ仕様のプロジェクトドキュメント作成の高度なテクニックまで。
Markdownの基礎
Markdownは、プレーンテキストのフォーマットをHTMLに変換する軽量なマークアップ言語です。 GitHub、GitLab、その他数えきれないドキュメントプラットフォームで使用され、 ソフトウェア開発におけるドキュメントの標準です。
なぜドキュメントにMarkdownを使用するのか？
- 人間が読みやすい: 読み書きが簡単なプレーンテキスト形式
- バージョン管理フレンドリー: Gitと完璧に連携
- プラットフォーム非依存: GitHubからドキュメントサイトなど多彩なサポート
- 高速な記述: 複雑なフォーマット不要、コンテンツに集中
- 変換可能: HTML、PDF、その他の形式に変換可能
基本的なMarkdown構文
見出し
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6テキストフォーマット
**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic***
~~Strikethrough text~~
`Inline code`コードブロック
```javascript
// シンタックスハイライト付きコードブロック
function greet(name) {
return `Hello, ${name}!`;
}
```
```python
# Pythonの例
def greet(name):
return f"Hello, {name}!"
```リンクと画像
[Link text](https://example.com)
[Link with title](https://example.com "Hover text")
[](https://example.com)リスト
# 番号なしリスト
- First item
- Second item
- Nested item
- Another nested item
- Third item
# 番号付きリスト
1. First item
2. Second item
1. Nested item
2. Another nested item
3. Third item引用
> This is a blockquote
> It can span multiple lines
>
> > Nested blockquotes
> > are also possibleテーブル
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
# 揃え付き
| Left | Center | Right |
|:-----|:------:|------:|
| Text | Text | Text |その他の要素
# 水平線
---
___
***
# 改行
末尾に2つのスペースをつけたテキスト
改行を作成
# エスケープ文字
*Not italic*
[Not a link]
`Not code`ドキュメント構造のベストプラクティス
README.md構造
適切に構造化されたREADMEは、プロジェクトの採用と保守にとって重要です。 最大の効果を得るために、この実証済みテンプレートに従ってください：
# プロジェクト名
プロジェクトが何をするか、なぜ有用かの簡潔な説明。
## 機能
- ✨ 機能 1: 簡潔な説明
- 🚀 機能 2: 簡潔な説明
- 🔧 機能 3: 簡潔な説明情報アーキテクチャ
価値を最初に提示
ユーザーが最も関心を持つことから始める - あなたのプロジェクトは何をし、なぜ彼らが使うべきなのか？
説明だけでなく実際に示す
価値を素早く実証するために、スクリーンショット、GIF、またはコード例を早期に含める。
段階的開示
クイックスタートから始め、必要な人には詳細情報を提供。
Code Documentation
シンタックスハイライト
適切なシンタックスハイライトはコード例をはるかに読みやすくします。 コードブロックには必ず言語を指定してください：
```javascript
// JavaScriptの例
const api = new APIClient({
baseURL: 'https://example.com',
apiKey: process.env.API_KEY
});
// 非同期関数の例
async function fetchUserData(userId) {
try {
const response = await api.get(`/users/${userId}`);
return response.data;
} catch (error) {
console.error('Failed to fetch user:', error);
throw error;
}
}
// クラスの例
class UserService {
constructor(apiClient) {
this.api = apiClient;
}
async createUser(userData) {
return await this.api.post('/users', userData);
}
}
```ヒント: JavaScript/TypeScriptコードブロックには`javascript`、`js`、`jsx`、または`typescript`を使用してください。
コード例のベストプラクティス
完全で実行可能な例
ユーザーがすぐにコピーして実行できる例を常に提供してください：
// ✅ Good: Complete example with imports and setup
import { DatabaseClient } from '@example/db-client';
const db = new DatabaseClient({
host: 'localhost',
port: 5432,
database: 'myapp'
});
async function getUser(id) {
try {
const user = await db.users.findById(id);
return user;
} catch (error) {
console.error('Error fetching user:', error);
throw error;
}
}
// 使用方法
const user = await getUser(123);
console.log(user.name);不完全な例を避ける
// ❌ Bad: Incomplete example missing context
const user = db.findUser(id); // Where does 'db' come from?
user.update({ name: newName }); // What if user is null?APIドキュメントの形式
良く構造化されたAPIドキュメントは、開発者があなたの関数を理解し、効果的に使用するのに役立ちます：
## APIリファレンス
### `createUser(userData)`
システムに新しいユーザーを作成します。
#### パラメーター
| パラメーター | 型 | 必須 | 説明 |
|-----------|--------|----------|--------------------------------|
| userData | Object | はい | ユーザー情報オブジェクト |
| userData.name | string | はい | ユーザーのフルネーム (2-50文字) |
| userData.email | string | はい | 有効なメールアドレス |
| userData.age | number | いいえ | ユーザーの年齢 (18-120) |
#### 戻り値
`Promise<User>` - 作成されたユーザーオブジェクト
#### 例
```javascript
const newUser = await createUser({
name: 'John Doe',
email: 'john@example.com',
age: 30
});
console.log(newUser.id); // 自動生成されたID
```
#### エラー
| エラーコード | 説明 |
|------------|-------------|
| `INVALID_EMAIL` | メールの形式が無効 |
| `EMAIL_EXISTS` | メールがすでに登録済み |
| `VALIDATION_ERROR` | 必須フィールドが不足 |高度なMarkdown機能
GitHubフレーバードMarkdown拡張
<!-- タスクリスト -->
## Todoリスト
- [x] 完了タスク
- [x] 別の完了タスク
- [ ] 未完了タスク
- [ ] 別の未完了タスク
<!-- 絵文字サポート -->
素晴らしい仕事！ :tada: :rocket: :sparkles:
<!-- メンションと参照 -->
コントリビューションしてくださった@usernameに感謝！
Fixes #123
See PR #456
<!-- 配置付きテーブル -->
| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |
| Text | Text | Text |
<!-- 折りたたみ可能セクション -->
<details>
<summary>クリックして高度な設定を展開</summary>
```javascript
const advancedConfig = {
cache: {
type: 'redis',
host: 'localhost',
port: 6379
},
logging: {
level: 'debug',
format: 'json'
}
};
```
</details>
<!-- Diff構文 -->
```diff
function greet(name) {
- return "Hello " + name;
+ return `Hello ${name}!`;
}
```
<!-- 数式(GitHub) -->
When $a
e 0$, there are two solutions to $(ax^2 + bx + c = 0)$:
$$x = {-b pm sqrt{b^2-4ac} over 2a}$$バッジとシールド
バッジでドキュメントに視觓的な指標を追加します：
<!-- Build Status -->
<!-- Version -->
<!-- Downloads -->
<!-- License -->
<!-- Coverage -->
<!-- Custom Badge -->
<!-- Multiple badges on one line -->
プロジェクトドキュメントの種類
必須ドキュメントファイル
README.md
プロジェクトの主要な紹介とクイックスタートガイド
- プロジェクト概要
- インストール手順
- 基本的な使用例
- 他のドキュメントへのリンク
CONTRIBUTING.md
コントリビューター向けガイドライン
- 開発環境のセットアップ
- コーディング標準
- プルリクエストプロセス
- 問題報告
CHANGELOG.md
バージョン履歴と変更内容
- リリースノート
- 破壊的変更
- 新機能
- バグ修正
docs/ Directory
詳細ドキュメント
- APIリファレンス
- チュートリアル
- アーキテクチャガイド
- デプロイメントドキュメント
CHANGELOG.mdの形式
適切に管理された更新履歴は、ユーザーがバージョン間で何が変わったかを理解するのに役立ちます：
# 更新履歴
このプロジェクトのすべての注目すべき変更はこのファイルに記録されます。
この形式は[Keep a Changelog](https://example.com/en/1.0.0/)に基づいており、
このプロジェクトは[Semantic Versioning](https://example.com/spec/v2.0.0.html)に従っています。
## [Unreleased]
### 追加
- 新機能の説明
### 変更
- 機能の修正
### 非推奨
- 削除予定の機能
### 削除
- 削除された機能
### 修正
- バグ修正
### セキュリティ
- セキュリティパッチ
## [1.0.0] - 2024-01-01
### 追加
- 初回リリース
- コア機能の実装ベストプラクティス:
- 進行中の変更のために常に上部に[Unreleased]セクションを保持する
- 一貫性のためにKeep a Changelog形式に従う
- 国際的な明確さのために日付形式はYYYY-MM-DDで記載する
ドキュメンテーションツールとワークフロー
ドキュメント生成ツール
GitBook
Git統合を備えたモダンなドキュメントプラットフォーム
- 美しく検索可能なドキュメント
- Git同期
- 協同編集
- カスタムドメイン
Docusaurus
MetaにReactベースのドキュメントフレームワーク
- 高速静的サイト生成
- バージョン管理されたドキュメント
- プラグインエコシステム
- MDXサポート
MkDocs
ドキュメント用Pythonベースの静的サイトジェネレーター
- マテリアルデザインテーマ
- 開発中のライブリロード
- プラグインアーキテクチャ
- 簡単デプロイメント
ドキュメンテーションワークフロー
# Example GitHub Action for documentation deployment
name: Deploy Documentation
on:
push:
branches: [main]
paths: ['docs/**', 'README.md']
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build documentation
run: npm run docs:build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/buildドキュメントレビュープロセス
ドキュメントをコードとして扱う
コード変更と一緒にプルリクエストにドキュメント変更を含める。
ドキュメントのバージョン管理
ソフトウェアリリースに合わせたドキュメントバージョンを維持する。
定期レビュー
コンテンツを最新かつ正確に保つために定期的なドキュメントレビューをスケジュールする。
ドキュメント品質チェックリスト
明確なプロジェクト説明と価値提案
動作するインストールとセットアップ手順
完全で実行可能なコード例
パラメーターと戻り値を含むAPIリファレンス
コントリビューションガイドラインと開発環境のセットアップ
ライセンスと連絡先情報
定期的な更新とメンテナンス
ドキュメントを作成する
私たちのMarkdownエディターでより良いドキュメントの作成を開始しましょう。コンテンツを リアルタイムでプレビューし、準備ができたらエクスポートできます。
Markdownエディターを開く