runaround’s diary

なんとなく、つれづれ

技術文書を書くということ

今年の目標は、「文章読解や作成能力を(´∀`∩)↑age↑」る! な、わけですが。

文章読解・作成能力検定

の4級問題集をやってみました。
4級なんてちょろいだろと思っていた自分を殴ってやりたい。
ひっかけと思われる問題に見事に引っかかりました。ずっと誤用してたわけですね。
杉下右京さんの前でうっかり使ったら、冷静に注意されてお小言いただいちゃいそうです。
現在3級の問題集に突入しています。
時候の挨拶とか難しいなー。実際に手紙やメールで書いたことないかもなーw

仕事に限らず毎日文章は何かしら書きますね。SNSやってればなおさら。
別にエモい文章を書きたいとかではないです。
せめてミスコミュニケーションによる他人への誤解だったり、
不快な印象を与えることは極力避けたいものです。
かといって極端に怖がってると何もかけないですけどね。
それにそんなに自分に影響力ないしw




ここ1年ほどは仕事で文章を書くことが多くなってきました。
というのも、私が望んで率先してやっているからなんですけど。


そろそろ転職して2年になります。
会社のプロダクトに関するドキュメントなどを見ていて、正直モヤモヤしていました。
何度読んでもわからない。初心者に冷たすぎる。わかる人にわかるんだろうけど。
とてもいいプロダクトなのに、これではこれから戸を叩く人が躊躇するんじゃないだろうかと。


改善したいと思っても、そもそも自分が理解できていないので手がつけられない。
ちょこっと開発もやってみましたがなんだかすっきりしない。
自分のクセでまずは大まかに全体を把握して掘り下げていくと理解がすすむことがわかっているので、一部の機能を集中的にいじって理解を広げていくのが苦手なんです。

一部をイジイジしてみる→えっ、これ他でもやってそうだけどどうなってんだろ、気になる→気になって一部に集中できない

なにか大まかに全体を把握できる方法はないかなーと思っていたところ、たまたま自サービスの情報収集とページ公開のタスクがあったので引き受けることにしました。
散らばっていたり問い合わせなどで協議されていた内容を集めて、有識者に正誤確認を取り、外部公開OK/NGを社内で決定し、ドキュメント化まで進めました。

doc4.ec-cube.net


もちろん外部の方に理解をすすめていただきたくて作成したものではあるのですが、一番理解が進んで嬉しかったのは私ですwww
また、今までは社内でも言語化されたものが少なかったのですが、個人の記憶に頼って間違った方向に話が進んでしまわないようになりました。


ありがたいことにサービスのユーザーも増えて、お問い合わせの数がどんどん増加してきました。
仕様や開発上の手続きに関して同様の問い合わせが増えてきて、専用のドキュメントの必要性が高まっていることがサポートからの相談でわかりました。
FAQページを作成して公開しようということになり、問い合わせの中からピックアップしてえいやっとドキュメント化しました。

doc4.ec-cube.net


サポートのチームのMTGに毎日参加をしていて、問い合わせ対応を一緒に考えているといろんな知見がたまります。
この知見が外部への情報公開にさらに役立ちます。
見ているとプロダクトの操作や運用方法への問い合わせも結構来ます。
うちのプロダクトはオープンソースで、コミッターさんや制作会社さんが強力なパートナーとしてノウハウをブログ記事などで公開してくださっています。
ですが公式の取説というか運用ドキュメントが存在していない状態でした。
強力なパートナーさんが運用マニュアルを作成し公開してくださっていたものを、譲渡いただくことになりました。
譲渡いただいた時点ではメジャーバージョン初期の情報だったので、公開後に最新バージョンの内容を加筆していってます。

www.ec-cube.net


機能をほぼ網羅したコンテンツを作成してくださっていたので(ほんとにありがたい)、読んでいてプロダクトへの理解も深まります。
また、コンテンツを追加する際は実際にプロダクトを触りながら解説を作成するので、新機能の理解も深まります。
一石二鳥どころじゃないんです。


また、プラグイン開発のパートナーさんからご提案いただいて内容を更新したパターンもありました。
プロダクトにプラグインという機構をつかって機能を追加する際に発生するトラブルの回避策を公開してほしい、というご提案でした。
もともとコンテンツとしてはあったのですが、パートナーさんからいただいた知見を元に再構成して公開しました。

doc4.ec-cube.net



紹介したドキュメント、もちろんまだまだ成長過程です。
不足もあるだろうしもしかしたら事実と異なるところもあるかもです。
サービスやプロダクトもどんどん成長していくので、一生懸命追いかけっこですね。


このようなドキュメントを整備し公開するということは、もちろん外部の方にとってメリットがあります。
ですが社内にも大きなメリットがあるということが最近わかってきました。
オンボーディングにも使えますし、既存メンバーにとってはあやふやな記憶で協議が空中戦になるのを防止できます。




とまぁ、勢いでドキュメントをがりがり作成してきたわけですが、ちょっと立ち止まってみました。
せっかくだからちょっと品質も上げていきたいよなぁ、と。
こういう情報収集して精査して公開するのって何かノウハウとかまとまったりしているのかしら?と。
ぐぐってみたら、ふと見つけました。

www.amazon.co.jp

www.amazon.co.jp

ヘルプサイトの作り方 WEB+DB PRESS plus Kindle版

www.amazon.co.jp

技術者のためのテクニカルライティング入門講座 Kindle版


このあたり読み漁ってみようかなー。
という自分へのメモ😁