Piece Frameworkドキュメンテーションガイド

Copyright (c) 2007 Piece Project, All rights reserved.

このドキュメントは、クリエイティブ・コモンズ・ライセンスの下でライセンスされています。

目次

1. Wikiページ名
2. ドキュメンテーションの種類
3. ドキュメンテーションの構成
4. 目次ページの構成要素
5. コンテンツページの構成要素
6. 文章のルール
7. 文章装飾のルール
8. ドキュメンテーションのレビュー

Wikiページ名

Wikiページ名はアルファベット、数字、アンダースコア等のURLエンコードされないものを使用します。これは、Wikiページで使用するAddCommentマクロ¹がURLエンコードされたWikiページを扱えないためです。

---

1. 1. http://trac-hacks.org/wiki/AddCommentMacro

ドキュメンテーションの種類

Piece Frameworkプロダクト毎のユーザーズマニュアル、HOWTO, トラブルシューティングを基本とし、必要に応じてクィックスタート・チュートリアルを準備します。

ドキュメンテーションの構成

ドキュメンテーションの基本構成は、章、節、項のWikiページ(コンテンツページ)及びそれらの目次ページとします。コンテンツページは文章の量に応じて章、節、項のうち適切なものをWikiページとして用意します。適切な粒度がわからない場合は、章でひとつのWikiページとしておき、大きくなったら複数の節のWikiページに分割するといいでしょう。また、ドキュメンテーションがごく少量の場合、このドキュメンテーションのように単一ページ構成からスタートしてもいいでしょう。

目次ページの構成要素

目次ページは、ぺージの先頭から、

1. ナビゲーション
2. ドキュメンテーションのタイトル
3. コピーライト
4. ライセンス
5. 目次

を配置します。詳細は実際のものを参照してください。

コンテンツページの構成要素

コンテンツページは、ページのタイトル、本文、ページ上下の目次ページへのリンク、ユーザコメントで構成します。詳細は実際のものを参照してください。

文章のルール

• 文章は「ですます調」とする。ただし、このリストのように適切でない場合は除く。
• 英数字は半角文字とする。
• 半角文字と全角文字の間にスペースは開けない。
• 全角文字の後の句点は「、」とする。
• 半角文字の後の句点は「,」とする。
• ()は半角のみとする。
• 用語やその使用方法はなるべく統一する。

文章装飾のルール

• Piece Framework及び第三者のプロダクトのマニュアルページへのリンクはインラインにて行う。
• 第三者のプロダクト、パッケージ、サイトの説明やWebサイトへのリンクは脚注にて行う。脚注にはFootNoteマクロ¹を使用し、現在の章、節、項の最後に書き出す。
• そのページ自身へのリンクは作成しない。
• 必要に応じて、脚注、画像を使用する。
• 画像については著作権に注意すること。

ドキュメンテーションのレビュー

新たにコンテンツページを作成し、そのリンクを目次ぺージに記載した場合、リンクの後に[レビュー待ち]という文言を追加し、レビューア(現在は久保のみ)のレビューを待ちます。

レビューアはレビュー待ちの文書を精査し、必要に応じて内容を修正します。また、必要であれば作成者に修正を指示します。 レビューと修正が完了すると、レビューアは[レビュー待ち」の文言を削除します。