分かりやすい文書を作成する勉強会に参加してきました


昨日30日に文書作成ワークフロー体験会という勉強会に参加してきました。これは講師を務めたアイデアクラフト代表の開米さんが、普段から文書改善研修で使っているテキストを使って、実際に文書改善の演習を行うというものです。

イベントのタイトルに「ワークフロー」とあったので、最初は文書作成業の話なのかと思っていましたが、そうではなく、ある状況に対して行動を起こしてもらうまでの工程の流れの事を指していました。文書を書くのが苦手という人でも、そのワークフローのどこでつまずくかは人それぞれだということで、それぞれの工程での着眼点についても説明がありました。

開米さんもおっしゃっていたように、文書の改善に当たって必要な観点(ここでは打ち手と呼んでいましたが)それぞれの知識はごくごく当たり前のことばかりで、割とどんなテキストでも散見されるような内容です。ですので、話を聴いているだけだとなんとなく分かった気になります。

しかし、実際に演習で「分かりにくい文書」を読解して図示するという作業をしてみると、これがなかなか難しい。つまり、どういう場合にどんな観点でどんな知識を適用するかというのがポイントで、そこはやはり場数を踏まなければならないんだろうと感じました。同じ課題でも、人によって成果物が異なり、各人の意図が反映されていて、それらを見比べるのも面白かったです。

こういったスキルは現場の改善に大いに役立つので、自分も実践しながら周囲にも広めていけたらと思います。


アイデアクラフト
http://ideacraft.jp/


ここでお知らせです。

25~35歳くらいの現場リーダーを対象に、
「理解されやすい業務フロー」を作るワークショップを開催します。
業務フローは業務の見える化には欠かせない基礎的な図式で、
これが書ける・読めるようになると
現場の業務改善・業務改革に役立ちます。

是非若いうちに身に着けておきませんか。

詳細・お申込みはこちらのopnlab社のサイトにて。


ドキュメント保守を怠る罠とツケ


今日はJSDGの中部ミニ研修会(チュンケン)が名古屋で開催され、参加してきました。研修会の発表について、細かい内容はここには書けないというか書いてはいけないことになっているのですが、エッセンスなら書いても赦されると思うので書いてみたいと思います。

人によっておそらく受取ったエッセンスは異なると思いますが、私が引っかかったポイントは、ドキュメントの保守についてです(ちなみに発表のポイントとはズレています)。とあるシステムについて、納品時にドキュメントも納品されるとします。システムが運用開始すると、機能追加や仕様変更は同じ業者に発注するとは限りません。

その時、ちゃんとドキュメントも更新されれば良いのですが、様々な理由で更新されない場合があります。費用を抑えるためかもしれませんし、納期を死守するためかもしれません。ですが一度それを許してしまうとアウトです。その後システムの現状を把握することが困難になってしまいます。そうなると改めて外部に現状把握のための調査を依頼しなければならなくなります。

別のある方は、7年前に作成したドキュメントが、実態は変更されているにもかかわらず、そのまま出てきたと嘆いておられました。それはドキュメントのメンテナンスがどれだけハードルが高いかを物語っています。それは単に意識の問題もあるでしょう。メンテナンスのための時間が取れないという可能性もあります。それ以上にスキルの問題が大きいのではなかと思います。

自分たちではできないからと割り切って外部に委託するというのは悪い選択肢ではありません。もちろんちゃんと勉強して自分たちでできるようにするというのはより良い選択肢であり得ます。ですが、自分たちでやるだけのスキルが有るにせよ無いにせよ、何もしないで放置するということほど悪い選択肢はないと思うのでした。

誰のためにドキュメントを作っていますか?


※この記事は法人化以前に投稿した内容の再掲です。

前回はドキュメント作成に関する書籍を紹介しましたが、関連する話題を一つ。

これは私だけかもしれませんが、私がまだ駆け出しの頃、SEあるいはPGとしての経験を積んでいってドキュメントのスキルレベルが上がるにつれて、ドキュメントはこうやって作るんだ…という意識から、ドキュメントはこうでなければいけないんだ…という意識に変化していきました。

するとプロジェクトの規模の大小に関わらず、がっちりとしたドキュメントを作成してしまう。融通が利かないというか、ドキュメント作成が一つの工程のようなものであり、それが目的になってしまったんですね。するとどうなるか。段々ドキュメントの作成コストの割合が大きくなっていきます。それだけではなく、修正などのメンテナンスコストもバカになりません。これでは本末転倒、いったい何のためにドキュメントを作成するのか分からない。それで悶々としていた時期がありました。

今ではもっと柔軟に、目的に適(かな)ったレベルのドキュメントを作成するように心がけています。システム開発で言えば、例えば内部設計書はもはや作っていません。それはたまたまアジャイルな開発を(いわゆる「アジャイル手法」を用いているという意味ではなく)行っているからかもしれませんが、単に設計思想が伝わるような挿絵やテーブル定義書を中心に、必要なものを追加するようにしています。

プログラムに限って言えばやはりソースコードが一番正確なので(ソースコードがバグっているということは往々にしてありますが、そういう意味ではなく)、ソースコードを読む手がかりになるものをいくつか作成すれば充分だと思います。むしろ実際のソースコードと相違のある詳細設計書の方が大切な時間と気力を奪われるという意味で有害であるとさえ思います。

それはソース中のコメントにも言えますね。大抵のソースコードは読めば分かる。だからちょっと奇抜な、セオリーから外れるパターンとか、結果的に複雑になってしまった場合に『何故、そんなコードを書いたのか』という点をコメントとして残しておいてくれると後から理解するのに役立ちます。(ただし、残すのはあくまでも「根拠」であって「言い訳」ではありませんよ)

話が逸れてしまいました。ドキュメントは体裁とか抜け漏れなく作ることも大切であることは言うまでもないのですが、ただ作れば良いというのではありません。(実際、検収を通すために作らざるを得ないのかもしれませんが、そういう場合でさえも)きちんと目的を捉えて、その目的を果たす――つまりドキュメントとして機能させることを第一に考えていきたいものです。

これでドキュメント作成の悩みがスッキリしました!


※この記事は法人化以前に投稿した内容の再掲です。

 IT業界に限った話ではないでしょうが、「ドキュメントは重要だ」ということが日常的に叫ばれています。ところがドキュメントが残っていなかったり、残っていても情報が古くて使い物にならないとか、そこまで行かなくてもどこに何が書かれているか分かりづらくて欲しい情報をすぐに探し出せないといったケースは意外とあるものです。

 ドキュメントの重要性について聞かされる割にはドキュメントの作成方法については教わることがなく、きっとその辺りに原因があるような気がします。

 それでも会社員時代は先輩や上司がサンプルを下さったりレビューしていただいたことで、なるほど設計書とは、報告書とは、手順書とは、議事録とはこういう風に書くのかということを学ばせていただきました。しかし、どことなく自信がない。ドキュメントの種類ごとの方式は確立しつつあっても、体系だったノウハウがないんですね。

 ある意味このまま自己流で…と開き直っていたところもあるのですが、たまたまドキュメント作成についての講演を聴く機会に恵まれました。ご本人の製品マニュアルのテクニカルライターとしての経験を踏まえたお話は大変分かりやすく、まさに目からウロコ。本書はその時の講演者が、その講演の内容をベースに手引書としてまとめたものです。

 内容は「そもそも」の話から、ちょっとしたテクニックまで、それも、組織やチームで共有できればそれに越したことはないが、個人レベルでもすぐに実践できるアドバイスまで盛り込まれています。例えば、「100点ではなく70点を目指す」「『管理する』『推進する』など意味のあいまいな言葉を使わない」「書けるところから書く」「同じ意味のことは同じ言葉で、違う意味のことは違う言葉で書く」といったものです。

 しかし、本書を読み進めていくと、ただの文章構成の手引書ではないなという感じがしてきます。例えば、常に目的と読み手を意識して、探しやすく・読みやすく・分かりやすく構成していくといった様子は、どこかアプリケーションのユーザインタフェースの設計にもつながるところがあります。ドキュメントの企画からリリースに至る過程もまるでシステム開発の工程のようで、『ものづくり』という営みの本質を見たような気がしました。

 何事にも目標を持つということは大切なことですが、ドキュメントも例外ではないんですね。ゴールを設定するという段階を踏むことで、ますますドキュメントが活き活きしてくる。「書かない技術」とあるのは、しっかり目的を持ってドキュメントを作りなさいというアドバイスではないかと思います。誰も使わないものまで作る必要はないというわけです。

 本書は業務でドキュメントを作成するすべての方、特にIT業界の最前線で今活躍しているあるいはこれから活躍しようとしているSE、PGの方々に是非手元に置いていただきたい一冊です。

———-
 書名:ドキュメントハックス ―書かない技術
 副題:ムダな文書を作り方からカイゼンする
 著者:石黒 由紀
 発行:毎日コミュニケーションズ/2007年9月1日
 ISBN:4-839-92428-7


あの人に気持ちを伝えたい!そんな時どうすれば…


※この記事は法人化以前に投稿した内容の再掲です。

私は文章で気持ちを伝えられなかったり、誤解を受けたりしたことがあります。また、相手の立場に立って物事を考えることができなかったために、相手を傷つけてしまったこともあります。これは日々の生活においてとても不自由なことではないでしょうか。

前々回のコミュニケーションにも通じるところがあるのですが、私は文章の書き方をまともに勉強したことはありません。少なくとも学校では深く教えてくれませんでした。教わったのは問題の解き方であって、頭の使い方ではなかったと言ったら言い過ぎでしょうか。

しかし、この「伝わる・揺さぶる!文章を書く」という本を読んで、頭を使うとはどういうことか、気持ちを伝えるとはどういうことかに改めて気付かされまし た。伝えると言うことは、伝える相手がいることが前提。…であれば、文章の読み手をしっかりと意識することが出発点になりますね。

本書のプロローグに大学入試を控えた17歳の女の子の小論文が例として取り上げられています。最初はまるで見当ハズレの、どちらかといえば読むに堪えない ほど未来も希望もないような文章だったのが、頭の使い方すなわち『考え方』を身に着けただけで見違えるほど生き生きとした文章になりました。しかも著者 は、文章の内容については一切口出しをせず、方法だけを指導したとのこと。考えるということの効能には驚かされました。

本書は前半で理論を、そして後半では実践を教えています。前半では、例を出しながら、なぜこういう文章では相手に伝わらないのかというポイントを押え、そ の上で、どうしたら伝わる文章になるのかということを丁寧に解説しています。後半では、更に具体的な場面を設定した上で文章の例を展開しており、応用すれ ばすぐに使えるほどケーススタディとして優れています。

自分の気持ちがほぼ間違いなく伝わるようになれば、仕事でもプライベートでも毎日の生活の様々な局面において、これまで考えられなかったほどの自由な人生を送ることができますよね。

———-
書名:伝わる・揺さぶる!文章を書く
著者:山田ズーニー 著
発行:PHP新書/2001年11月29日
ISBN:4-569-61736-0