📝

「エンジニアが一生困らないドキュメント作成の基本」を読んだ

に公開
ドキュメンテーション
idea

今更ながら「エンジニアが一生困らないドキュメント作成の基本」を読んだので、発見や学びをまとめました。
https://www.socym.co.jp/book/post-19000

知りたいこと

  • 良いドキュメントの書き方
    実務でプログラムの仕様や検証結果などをまとめていましたが、自己流でやっていました。
    なので粒度や書き方がまだ掴めていないのではと若干心配があります。

  • 人に対する文章の書き方
    私はプロンプトを書くのにあたって正確性を重視して書くのですが、情報の粒度が必要以上に細かくなったり理解しづらい文章になっています。
    職業上プロンプトを書くことが多いので目的語や主語を明確にするクセがついてしまいました。
    細かい人だと思われやすいです。
    人間用にカリブレーションしなくてはいけないですね。

  • ドキュメンテーションって時間かかるから短縮できない？
    私にとって、これが一番問題です。
    凝り性なので、正確に記録を残したり書こうとするとやたら時間がかかるものです。
    かといって、書くプロセスを省略すると思わぬところで足を掬われます。
    そして上流工程を担うなら文章力はさらに重要になります。どうしたものか….

知りたいことに対する感想・考察

  • 良いドキュメントの書き方

    • 目次とアウトラインの関係(140P付近)
      ドキュメンテーションとは、事実を書き下すことだと誤解しておりました。
      自分は書く前にアウトラインを適切に置けていないのだと思い知りました。
      必要な粒度や骨組みも勉強になりました。読み手と書き手の目線を交互に行き来しながら書きます。

  • 人に対する文章の書き方

    • 文章の読み方(60P付近)
      正しい文章を書くには文章が相手にどう伝わるか、どう読まれるかを考えなければいけません。
      なのでドキュメントの読み方を最初に知るというのは道理が通りますね。
      ただ、文章を適切に読むのは非常に難しいことです。
      応用情報技術者試験など文章を適切に理解する試験を通して、実践的に学んでも良いかもしれません。
    • わかりやすい文章を書く(185P付近)
      生成AI向けに文章を書きすぎて、人間が読んだらどう思うかが抜けていました。
      何を理解してもらえればいいから何をわかりやすく書く、といった視点をなくしていました。
      書籍からコツを得たので、実践していこうと思います。

  • ドキュメンテーションって時間かかるから短縮できない？

    • ChatGPTで効率よく書く(213P)
      近年のLLMは精度が向上しているので、こういった使い方をしている人も多いかと思います。
      確かにLLMを利用すれば時間を短縮できます。
      ただし、最後は人の目で適切な内容であるか確認する必要があると思います。
      レビューをする際には何が良いか、何が悪いかを知っている必要がありますね。
      適切に書けるということは物事を理解していることと近いのでは…？

さらに学びたい点

  • 文章力の鍛え方
    書き方を理解しても実際にできるようになるのは難しいと思います。
    そういう時は下記の書籍などで学ぶのが良いと思います。
    メールや文章の書き方をケースごとに解説しつつ、実践問題もあります。

https://str.toyokeizai.net/books/9784492533925/

  • 観察力
    物事の要素を分けたり、それを言葉で表現する力が必要だと思いました。
    「テーマを分解する」章などで言及はありましたが、もっと学ぶべきことだと感じました。

まとめ

こうして文章で整理すると何を学んだか、今後どう活用していくかが明確になるので良いです。
ドキュメントを書く場数も必要だと思いました。
過去のドキュメントにはどのような項目や粒度で記載されているか学べる環境は大切にした方が良いですね。

Discussion