📝

次世代 Web カンファレンス 2023 Technical Writing セッションでは話し足りませんでした

2024/01/04に公開

ハッシュタグは、#nwc_technical_writing でした。togetter に Technical Writing セッションのまとめ がありますので、こちらもぜひお楽しみください。

個人的には、普段の Technical Writing meetup と比べて流量の多さに圧倒されましたw Technical Writing meetup のハッシュタグは #TWMeetup です (宣伝)。よかったら meetup のほうにもぜひお越しください。

さて、togetter のまとめを見ていると、そういえば、こんなことも言いたかったなーということがいくつか出てきたので、書き残しておこうと思います。

もしまだセッションを聞いていただいていない方がいらっしゃいましたら、こちらからどうぞ!
https://www.youtube.com/watch?v=mVGz5-F7_hY&t=16228s

うちわの綴り

shoko さんが作ってくださっていたうちわは、本番前日の投稿では余計な文字が入っていましたが、本番では魅力的な ❤ になっていました。さすがでした!

缶バッジ

超羨ましかったので作りましたw

聞き手のレベルを意識してしまったw

「(初心者など)聞き手のレベルを意識せず、話したいレベルで話してください。」というようなことを言われていたのですが、ほぼ「話したいレベル」=聞き手のことを意識したレベルになってしまいましたね。一種の職業病というか癖かもしれませんw それでもお楽しみいただけていたら嬉しいです。

ということで、冗談はこれくらいにして、この記事の本編に行きましょう!

テクニカルライターの存在価値は?

「テクニカルライターがプロダクトやチームに貢献できること」という記事を書きました。ぜひご覧ください。

https://zenn.dev/yazakimakoto/articles/5c0864232bb2df

テクニカルライターになる前の仕事がいろいろあるっていうのは興味深い話でしたね。エンジニアだったりサポートメンバーだったり営業だったりからテクニカルライターに転身する方もいらっしゃるようです。私は初めからテクニカルライターだったというほうでしたが、もっとソフトウェアを使える世界になるように力を尽くしたいと思って始めたと記憶しています。今はだいぶソフトウェアが浸透してきていて、いい感じだなぁと思っていたりします。

どこに書くか問題

API リファレンスとドキュメントの話を例に、今から書きたいと思っていることは「いったいどこに書くと適切なのか問題」が話に出ましたね。

API 単体の説明はできる限り API リファレンスに載せたいし、複数の API を組み合わせる場合は API リファレンスで説明しきれないのでドキュメント (API リファレンスではない説明書) に書く気がします。弊社のドキュメントを例に挙げると、「SORACOM API リファレンス」のことをイメージしながらセッションでは「API リファレンス」と言っていました。また、「IoT SIM の名前を設定する」みたいなページのことをセッションでは「ドキュメント」と言っていました。

(この辺は聴衆のことを考えない物言いができてて良かった気がしますw)

結局どこに書くか問題はいい解決法が見つかっていなくて、今は「自分が問い合わせを受けたときに見つけられそうなところに、いったん書いておく」が正解じゃないかなと思っています。そして、しばらくしてから (3 か月後の自分になったときに) この辺に書いたんじゃなかったっけ? というところを探して見つからなかったら、そこにもコピーして増やしていくのがいい気がしています。

本当は「みんなが見に来る場所」を客観的に知ることができるのが最高だと思うのですが、その方法がないので、上のようにやっている感じです。ひょっとしたら「みんな」に相当する人に「どこに探しに行きますか?」って聞いてもいいかもしれないですね。

ドキュメントは誰のために書くのか

「ドキュメントを誰のために書いていますか」という記事を書きました。こちらもぜひ!

https://zenn.dev/yazakimakoto/articles/9049048c649de2

ドキュメントを正確に書くの大変じゃない?

本当に大変です。でも揺らぐことなく正確に書きたい。それは好き嫌いとか正確の話ではなくて未来の自分を助けるためだと思っています。「なぜドキュメントを正確に書きたいのか」という記事を書きました。この記事を読んでいただいて、なるほど、合理的な考えかただ。テクニカルライターの特殊な性質ではなかったのか。などと思ってもらえると嬉しいです。

https://zenn.dev/yazakimakoto/articles/2aa1ce0d1a88c6

GPT (延長戦)

本当は LLM と書くべきですが、そこをあえて GPT と書きますね。LLM 的興味は無くはないですが、実際仕事でつかえるのは今のところ GPT なので。

90 分の中でも少し GPT の話をしたかったのですが、本編ではとても入らずw 延長戦で GPT の話をしよう!ということにして、少し話をしてきました。最後の枠は完全撤収 20:00 を守らなければいけなかったので、やっぱりちょっと話足りない感じはしましたが…。

個人的には、Technical Writer は GPT の影響を強く受けるだろうと思っています。しかし一方で、テクニカルライターがプロダクトやチームに貢献できること に書いたことを全部 GPT が肩代わりできるかというと、そういう時代が来るのはもう少し先かなと思っています。

どちらかというと、テクニカルライターとして GPT を使わない手はないのでは…? というポジティブな気持ちが強いです。たとえば、いまひとつ納得できる表現ができなかったときに手伝ってもらったり、翻訳を手伝ってもらったり、エンジニアが書いたコードを理解するときに手伝ってもらったり、エンジニアから渡された複雑な情報をまとめてもらったりできそうです。ほかにも、校正を手伝ってもらうこともできますし、情報の過不足を指摘してもらうこともできます。Q&A ボットを作れば、ボットが質問に答えられるドキュメントになっているか (ドキュメントがボットにとってわかりやすいか) を客観的に評価することもできるでしょう。

あれこれ考えてみると、テクニカルライターは「ドキュメントを書くこと」が目的なのではなくて、「ソフトウェアを正しく使ってもらうこと」「ユーザーが目的を達成することを手伝うこと」を目的にしているはず、と私は考えているようで、今はまだ猫の手でも GPT の手でも借りたいですね。

ということで、あれこれ雑に書いてみましたが、このシリーズをときどき書き直したり追記したりして育てていくかも。お楽しみに。

Discussion