わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要 - Qiita

はじめに エンジニアなら誰でもたくさんのドキュメントを読むことになります。 その中にはわかりにくいドキュメントも少なからずあると思います。 自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。 そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。 また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。 ここで扱うドキュメントの種類 ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定しています。 Qiitaの投稿やブログの記事といったものでも共通する部分は多いのですが、これらには他にも重要な要素があると思うので、ここでは扱いません。 わかりにくいドキュメント=全体像が掴めないものが多い 先ず、わかりにくいドキュメントとはどんなものでしょ

[minoru0707]

ワードで書く。それだけだ。

[stabucky]

そんなこたあ、どうでもいいんだ。エクセルで長文を書くな。

[tuka8s]

エクセルやパワーポイントでボリュームのあるドキュメントを書かないことが一番親切ではないだろうか、、、

[otherworld]

為が偽になっているところがあるのはコピペ対策かな。気になった。

[perl-o-pal]

excel/ppで書くと文章の構造変えた時に更新漏れとか出て面倒くさい。あれらは長文書くためのツールではないと思うけど、偉い人はその辺分かっとらんのです。

[kyokyokyo-wanuo]

めもめも

[jakiyama]

「おわりに」とか「結び」の代わりに「まとめ」ってセクション名にする風潮は、ドキュメントがわかりにくくなる原因の一つだと思う。

[YAK]

"この投稿のある一文には意図的に誤字・脱字を7つ仕込んであります" 何の偽だよ…

[verda]

目次読まないしテキトーに検索して必要な所を見てしまうので申し訳ない気分になった

[zou3dazou]

冒頭に概要を書く

[beerbeerkun]

語数を減らすのと一文を短くする努力も必要だよね。接続詞、形容詞、副詞をむやみに使うと情報量過剰になって趣旨が伝わりにくくなる。極力控えるべし。

[miau]

"ドキュンメトを判りやくする偽には全体象を把握できることの方がよリ需要なことです。" ここは誤字・脱字を色々と仕込んだ一文ですね。「為が偽になっているってことは Try-Code 使用者？」と思ったけど違ったかー…。

[tmatsuu]

大事

[JHashimoto]

“一番重要なのは、詳細に入る前に概要を書くことです。" "詳細の理解に役立つもの、事前に知っておくべきことなどを書きます。 具体的には次のような事を必要に応じて書きます。”