Software Design 2022年8月号執筆記

はじめに

TIG DX Unitの武田です。

先日（2022年7月15日）発売された技術評論社の Software Design 2022年 8月号に寄稿させていただきました。
まずはじめに、このような寄稿の機会をくださった技術評論社の方々には、心からお礼申し上げます。

具体的には、第1特集の「Web APIの作り方」という4章構成の特集の「第4章 OpenAPIを使ったWeb API開発の実際」という部分を、私と弊社エンジニアの宮崎、大岩の3名で担当いたしました。

3名とも技術商業誌への寄稿は今回が初めてとなりますが、執筆を進める中で苦労した部分や、意識した部分など本記事でお伝えできればと思います。

Software Design とは

技術評論社が出版している月刊の技術情報誌となります。
ソフトウェア業界のエンジニアにとっては説明不要と言っていいくらい鉄板です。

毎月様々なテーマについて特集を組んで取り扱っており、プログラミングだけでなく、OSやネットワークまで、その内容は多岐に渡ります。
入門者・初心者向けの内容から実践的な内容も多く含まれているので、新人からベテランまであらゆるエンジニアにおすすめできる雑誌です。

執筆のきっかけ

Future Tech BlogでOpenAPIをテーマとして取り扱った記事を見ていただき、OpenAPIを活用した開発事例を取り上げたいとのことで会社宛に依頼をいただきました。

自社のブログがきっかけとなってこのような依頼がくるのは大変ありがたいことですね。
これからも積極的に社外に情報を発信していこうというモチベーションにもなります。

きっかけとなった記事を含め、OpenAPIについて触れている記事を紹介しておきますので気になる方はぜひ読んでみてください。

執筆文量

8ページ程度（1ページあたり最大1,680字）の文量で依頼をいただき、結果としては11ページ、約15,000字となりました。

執筆のフロー

執筆作業はおおよそ下記のようなスケジュールで進めていく形となりました。
黒塗りしている矢羽の「原稿作成」と「誌面修正」が弊社の担当となります。

原稿の作成期間はおおよそ3週間程度というスケジュールでした。
おそらく通常のスケジュールと比べると若干タイトなのかもしれませんが、依頼いただいた8ページという文量を考えると無理のないスケジュールだと思います。
何より技術評論社の方には、我々の本業の状況も考慮してスケジュールについて大変丁寧にお気遣いいただき、とても感謝しております。

以下、「執筆依頼を受けてから打合せまでの進め方」「原稿作成の進め方」「誌面修正の進め方」という3部構成で詳細について説明していきます。

執筆依頼を受けてから打合せまでの進め方

執筆依頼を受けてから、まずは社内でOpenAPI関連のブログを投稿しているエンジニアをはじめとしてフラットに執筆者を募りました。
8ページという文量を考慮すると1-2名が適正人数かなというところですが、ちょうど中堅、若手からそれぞれ1名手が挙がったので、ベテランの私率いる3名で執筆させていただくことにしました。

Software Designは入門者から経験者まで幅広い読者層をターゲットとしていると思いますので、ベテラン、中堅、若手のそれぞれの視点で内容を精査できたのは結果的に良かったのではないかと思っています。

原稿作成の進め方

見出しの作成

まずは見出しの作成です。
技術評論社の方からいただいた大枠の見出し案をベースに、3名でアウトラインについて叩きを持ち寄りディスカッションして決定しました。
意識したのは、依頼を受けた4章の中だけでなく、1章 ~ 3章の前章の見出しを踏まえた上で、整合性が取れているか、重複する部分がないかということです。幸いにも見出し案を考える際に、前章の見出し案を共有いただけたのでこの辺りはスムーズに進めることができました。

また技術評論社の方に見出しを提出する際は、見出しだけでなく、どのような内容をどの程度の文量記載する予定かを可能な限り共有することで、手戻りのリスクを極力小さくするようにしました。

こうして約3日程度で見出しの確定に至りました。

分担・内部スケジュールの決定

見出しが決まったら、次に誰がどの部分を執筆するか分担を決定します。
今回は見出し別にそれぞれ知識や実務経験のある領域をベースに、ブログなどの執筆経験値や業務状況なども踏まえて分担を決定しました。

内部のスケジュールとしては、原稿の締め切りをゴールとして、1週間で各自担当部分を執筆、1週間でマージ及び全体の推敲、残り1週間をバッファとして組み立てました。
個人での執筆と異なり、複数人での執筆は、各担当部分をマージしてから全体として文章のゆれがないか、整合性がとれているかを確認するのに時間を要するため、スケジュールに余裕を持たせておいて結果的に正解でした。

TIPsですが、業務外の作業として土日にゆっくり時間をとって作業をするケースが多いと思うので、進捗確認などのミーティングは月曜日にしておくと効果的です。

個別原稿執筆

分担とスケジュールが決まったら各自執筆作業に移ります。
執筆のツールは基本的に自由ですが、全員マークダウンに慣れ親しんでいることもあり、Qiitaの限定共有機能を利用してマークダウンで作成した記事を共有する形を取りました。
各自が作成した原稿のマージ作業は、私が手作業で行いましたが、文量や人数がこれよりも多くなる場合は、共同編集ツールを使うと良いでしょう。（この辺りは弊社内の事情もあり、今回は利用を見送りました。）

作成した記事のレビューは私が中心となって行いましたが、その際に意識したのは下記の4点です。

用語の使い分け方を明確にし、表記ゆれをなくす
OpenAPIに関連する用語はいくつかあり（OpenAPI, OAS, OpenAPIドキュメント, OpenAPI定義など）全体としてどのような意図で用語を使い分けるのかを内部で認識を合わせ、統一しました。
やってみた系の内容に終始していないか
執筆テーマが「OpenAPIを使ったWeb API開発の実際」ということで、OpenAPI関連のツールを使用した設計手法や開発手法を紹介する形になるのですが、ツールの利用手順などは極力ライトにし、内容としては苦労点や工夫点が盛り込まれた現場感の強い内容を盛り込めるよう意識しました。
文量を削るのは後回し
事前に見出し単位でおおよその文量は定めていますが、文章を削る作業は全体をマージした後の段階とし、個別に原稿を書く際には無理に文章を削りすぎないことを全員で意識するようにしました。
理由としては、初めから文章を削ってしまうと各見出しごとの内容が満遍なく薄くなってしまう可能性があり、全体としてみた時にメリハリのない記事になってしまう可能性があるため、これを避けることを意図しています。
他社の権利を侵害するような内容が含まれていないか
文章やソースコードを引用する場合は、適切に行われているか。特に図を挿入する場合に、利用しているアイコンや画像など著作権違反となるものがないか、を入念にチェックしました。アイコンや画像については商用利用可能なものであっても、著作権表示が義務付けられているものもあるので、この辺りは要注意です。
原稿の図については提出後に技術評論社の方で改めて作図する形になるため、最終的には問題は発生しないと思われますが、我々としては原稿の段階からパブリックドメインのアイコンで統一するように意識しました。

このようなことを意識しながらレビューをしていて、私が常々思うのは、魂込めて書いた文章を指摘するというのは、指摘する方もされる方も精神衛生上あまり良いものではありません。
特に明確な誤りを正すような指摘であれば良いのですが、文章のテイストや書きっぷりなど個人の好みが現れる部分に対して、全体での統一感を意識した結果、指摘を行わなければならないケースについては、どうしてもレビュワーの想いが強くなってしまう傾向があります。
この辺りは、自分自身の考えや想いを明確にした上で、執筆者本人の想いも最大限尊重しつつ丁寧にコミュニケーションを取りながらすり合わせることで、モチベーションを低下させないようケアしながら進めていくことが大切だと考えています。

個別原稿のマージ・全体推敲

個々の原稿が仕上がったら、全体として1つの原稿にマージした上で推敲を行います。
この段階で意識したのは、なるべく早めに技術評論社の方にドラフトの原稿を共有しフィードバックをいただくことです。
今回は完成原稿を提出するまでに、前半部のドラフト、後半部のドラフトの2回に分けてドラフトを共有させていただきました。

実際の誌面にした際のページ数や他の章との内容の重複についてこの段階で確認できるため、ここでのフィードバックをもとに全体原稿をブラッシュアップしていきます。
最終的には11ページの文量に着地する形となりましたが、11ページという文量はいざ書いてみると思ったより少なく、内容が薄くならないよう文章を濃縮していく作業は想像よりも大変です。

Software Designはページ数こそ薄いものの、内容が濃いものになっているのは、世の中のエンジニアが試行錯誤してエッセンスを詰め込んでいる賜物なのだと気づき、改めて素晴らしい技術誌だと実感しました。

誌面修正の進め方

原稿を提出した後は、技術評論社の方で編集・レイアウトが行われ、完成した誌面PDFが共有されます。
（私は発売日よりも、誌面をみたときが一番テンションが上がりました。）

インターネット上のブログであれば後から修正ができますが、紙媒体の雑誌はそれができないということもあり、文章のチェックはいつもよりも時間をかけて、執筆者全員で2回、3回と行いました。

特に誤字・脱字をはじめとし、利用しているライブラリやツールのバージョンは合っているか、リンクが適切かどうか、記載したプログラムは実際に動くものになっているか、など細かい部分まで確認を怠らないようにしました。

おわりに

以上のプロセスを経て、無事 Software Design 8月号の発売を見届けることができました。
通常書いているブログとは異なり、複数人で協力しながら作り上げていくチーム感であったり、限られたページ数での記載内容の取捨選択であったり、いつもとは違う刺激を感じながら、楽しく執筆をさせていただくことができました。

実際の内容については本記事では触れていませんが、実際の現場でOpenAPIを使ってどのように設計・開発・テストを進めているのか、具体的な事例とともに紹介していますので、気になる方はぜひ手にとっていただけると幸いです。

また今後執筆の機会がありましたら、ぜひとも積極的に関与させていただきたいと思っておりますので、弊社のブログなどを見て気になった方はぜひお声がけいただけますと幸いです。