SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

DeveloperZine(デベロッパージン)- エンジニアの意思決定を支える技術情報メディア ProductZine

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

テクニカルライティング作法・外伝

「簡単な話から始めよう!」~ソフトウェア開発者に贈るテクニカルライティングの極意

テクニカルライティング作法・外伝 第7回

まとめていっぺんに書かれると分からない

 例えば、自動車のアクセルペダルにはどんな機能があるでしょう。ご存知の方は、その知識がないものとして、次の例文を読んでみてください。

ハイブリッドカーXXのアクセルペダルの機能
(知らない人への解説としては不適切な書き方)

 停車時にアクセルペダルが踏み込まれたとき、センサーが進行方向に障害物や人を検知していたら警告を発します。そうでなければ、必要に応じてエンジンを始動し、モーターまたはモーターとエンジンの出力を増大させるように制御し、出力の増大を検出したら自動ブレーキをリリースします。

 走行中にアクセルペダルがさらに踏み込まれたときは、必要に応じてエンジンを始動し、モーターまたはモーターとエンジンの出力をさらに増大させるように制御します。

 走行中にアクセルペダルが部分的に戻されたときは、モーターまたはモーターとエンジンの出力を減少させるように制御します。このとき、エンジン出力が不要になれば、エンジンは停止させます。また、アクセルペダルが完全に戻されたときには、モーターへの電力供給も停止して回生ブレーキを作動させます。

 なお、走行中はアクセルペダルの踏み込み量に関わらず、バッテリーの残量に応じてエンジンを動かします。また、高速走行時にはモーターよりエンジンの効率が良いため、エンジンだけで必要な出力が得られるときはモーターを停止します。このような切り替え時には、モーターとエンジンの合計出力が急変しないように制御します。

 「なんじゃこりゃあ!?」って感じかもしれませんが、今どきのハイブリッドカーはこのような複雑な制御をやっているんです(特定の車種ではなく、架空のものです)。ちょっと脱線しますが、いまや自動車もソフトウェアのかたまりです。しかもこれは例文ということで、かなり簡略化しています。実際にはさらに、変速機の制御や、エンジンを駆動系から切り離して発電機としてだけ使う制御、あるいは、カーブを曲がっているときに車体の安定をよくするための出力制御だとか、カーブを曲がり終わったときにスムースに加速するためのエンジン回転数保持制御などと、アクセルペダルひとつだけでもあきれるほど複雑なプログラムが組まれています。

 さて、なるべく正確な内容をきちんと解説しようとして上のような文章にしてみましたが、いかがでしょうか? 知らない人に向けた解説としては、これでは「難しくてさっぱり分からないよ!」と言われてしまうでしょう。

不正確になったとしても簡単な説明から始める

 そこで、たとえ不正確になったとしても簡単な説明から始めるようにすると、分かりやすくなります。上のアクセルペダルの説明の冒頭に、次の文章を挿入したらどうでしょう。

  • アクセルペダルはエンジン出力を調節します。踏み込まれると加速し、戻されると減速します。

 この文章が先の解説の先頭にあれば、ずいぶん理解しやすくなると思いませんか。先の解説に比べると、この文章だけではずいぶん不正確です。モーター制御がありません。発進しない場合があることも分かりません。しかし、不正確ではあっても大雑把にこういうものだという説明を最初にすることで、その後の詳細な解説を理解する助けになるんです。

 不正確になったとしても簡単な説明から始める。そして、不正確な部分を補うように説明を追加していく。最後まで読めば、正確な知識が得られる。そのようなステップアップしていく解説の仕方のほうが分かりやすくなります。先の解説をそのような書き方に直してみると、次のようになります。

ハイブリッドカーXXのアクセルペダルの機能
(知らない人への解説として適切な「ステップアップ型」の書き方)

 アクセルペダルはエンジン出力を調節します。踏み込まれると加速し、戻されると減速します。

 エンジン出力といっても、実際の動力源はモーターとエンジンです。モーターを優先して使い、エンジンは必要に応じて自動的に動かしたり止めたりします。その際には、モーターとエンジンの合計出力が急変しないように制御します。エンジンを動かすのは、次のような場合です。

  • モーターだけではまかなえない出力が必要なとき
  • バッテリーに充電する必要があるとき
  • エンジンの方がモーターよりも効率が良くなる高速走行のとき(このときはエンジンを優先して使い、モーターはできるだけ使いません)

 なお、次のような場合には、エンジン出力のほかにも制御を行います。

  • 停車時:センサーが進行方向に障害物や人を検知していたら、アクセルペダルが踏み込まれてもエンジン出力を上げず、警告を発します
  • 発進時:アクセルペダルが踏み込まれ、車体が動き出す出力に達したら、自動ブレーキをリリースします
  • 減速時:アクセルペダルが完全に戻されたら、モーターへの電力供給も停止し回生ブレーキを作動させます

 前述したように、まず大雑把な話を最初の段落に書いています。第2段落でも、簡単に「エンジンは必要に応じて自動的に動かしたり止めたりします」とだけ説明しておいて、どういうときに動かすのかという正確な話は後回しにしています。さらに例外的な話は、最後に持っていきました。

 もう一度、最初の解説を読み返してみてください。解説している内容は同じです。でも、こちらの「ステップアップ型」解説の方が読みやすいでしょう。

次のページ
商品単価取得メソッドの例

関連リンク

この記事は参考になりましたか?

テクニカルライティング作法・外伝 連載記事一覧

もっと読む

この記事の著者

biac(ばいあっく)

HONDA R&Dで自動車の設計をやっていた機械屋さんが、技術の進化スピードに魅かれてプログラマーに。以来30年ほど、より良いコードをどうやったら作れるか、模索の人生。わんくま同盟の勉強会(名古屋)で、よく喋ってたりする。2014/10~2019/6 Microsoft MVP (Windows Devel...

※プロフィールは、執筆時点、または直近の記事の寄稿時点での内容です

この記事は参考になりましたか?

この記事をシェア

CodeZine(コードジン)
https://codezine.jp/article/detail/11642 2019/08/07 11:00

イベント

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー