最近のウェブ開発では各機能ごとをAPIでつなぎ込む時代になっています。 そのため、各チームが開発をしていく上で、 他のチームにAPIの仕様を伝える方法をきちんとまとめておく必要が出てきています。 そんな中でAPIドキュメントにどのような役割が求められていて どのような選択肢があるか、一旦自分の把握している知識をまとめています。 (ここで書いているAPIは、httpでアクセスしたら、JSON形式でレスポンスを返すウェブサービスのAPIを指しています) APIドキュメントを用意する上で、すぐにぶつかる壁 APIドキュメントを用意する場合に、何も考えずにExcelやwikiにまとめると、早い段階で メンテナンスのコスト の問題にぶつかります。 『APIドキュメントを書く時間がない』 『本当にドキュメント通りの結果が返ってくるか、試してみないとわからない』 『実際に返ってくるAPIとレスポンスが違
上の設定では二つの機能が登録されています。 SentenceLength 文の長さ自体を検査する機能。上記の設定では文の最大長を100文字に設定している。 CommaNumber 文中のコンマの数を検査。デフォルトでは最大四つ。 上の設定はどれも文の長さに関連する検査です。たとえばコンマの数や同一単語の複数回の利用は文が長ければ検査に引っかかる可能性が増えます（注: DoubledWord は削除しました 2016/05/11）。先に述べたように一度文を短く揃えてからが、本格的な文書の校正の開始です。文が短く揃っているために文書が頭に入ってくるスピードが増して校正作業がスムーズにすすみます。 表現に関する設定 次に文書内の表現に関する機能を加えてみます。 <redpen-conf lang="ja"> <validators> <validator name="SentenceLength
最近はブログを始めマニュアルや仕様書など技術文書を書く機会が多くなってきました。 技術文書はわかりやすさが重要だと思うのですが実際は書けていません。 どうしたらわかりやすい文書が書けるのだろうか？と調べていたら RedPen というツールを見つけたので早速試してみました。 RedPen とは？ RedPen とはプログラマや記者が規約に従って文書を記述するのをサポートしてくれるオープンソースのソフトウェアツールです。 プログラミングが規約に従ってコーディングされているかチェックするように、RedPen は自然言語で記述された入力文書の検査を自動化してくれます。 RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査でき
運営元のロゴ Copyright © 2007-2024 All Rights Reserved by Gijutsu-Hyoron Co., Ltd. ページ内容の全部あるいは一部を無断で利用することを禁止します。個別にライセンスが設定されている記事等はそのライセンスに従います。
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く