はじめに エンジニアなら誰でもたくさんのドキュメントを読むことになります。 その中にはわかりにくいドキュメントも少なからずあると思います。 自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。 そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。 また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。 ここで扱うドキュメントの種類 ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定しています。 Qiitaの投稿やブログの記事といったものでも共通する部分は多いのですが、これらには他にも重要な要素があると思うので、ここでは扱いません。 わかりにくいドキュメント=全体像が掴めないものが多い 先ず、わかりにくいドキュメントとはどんなものでしょ
![わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/9055f549b0d797ab1f5d0f2da4ee6d05e76255e8/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-9f5428127621718a910c8b63951390ad.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTkxNiZoPTMzNiZ0eHQ9JUUzJTgyJThGJUUzJTgxJThCJUUzJTgyJThBJUUzJTgyJTg0JUUzJTgxJTk5JUUzJTgxJTg0JUUzJTgzJTg5JUUzJTgyJUFEJUUzJTgzJUE1JUUzJTgzJUExJUUzJTgzJUIzJUUzJTgzJTg4JUUzJTgyJTkyJUU2JTlCJUI4JUUzJTgxJThGJUUzJTgxJUFCJUUzJTgxJUFGJTIwJUUzJTgwJTlDJTIwJUU1JTg1JUE4JUU0JUJEJTkzJUU1JTgzJThGJUUzJTgyJTkyJUU2JThBJThBJUU2JThGJUExJUUzJTgxJUE3JUUzJTgxJThEJUUzJTgyJThCJUUzJTgxJTkzJUUzJTgxJUE4JUUzJTgxJThDJUU5JTg3JThEJUU4JUE2JTgxJnR4dC1jb2xvcj0lMjMyMTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LWNsaXA9ZWxsaXBzaXMmdHh0LWFsaWduPWxlZnQlMkN0b3Amcz0wNWFiNWUwNjEwOGUzYTQwNTM1ZWU3YWVjM2U2MGMzNQ%26mark-x%3D142%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTYxNiZ0eHQ9JTQwdGFnMTIxNiZ0eHQtY29sb3I9JTIzMjEyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnM9NWViOTQyZDIyNTIzOTQ0YzM2YWU1Y2ZlZTY4NmQ5ZTQ%26blend-x%3D142%26blend-y%3D491%26blend-mode%3Dnormal%26s%3D8474c048429c86d46ef1f53c7bd28e7d)