レポートの書き方（Jenkins勉強会レポート編）

「明日からがんばろう」という発想からは・・・どんな芽も吹きはしない・・・・・・・・・・・！
そのことに２０歳を超えてまだ・・・わからんのか・・・・！？
明日からがんばるんじゃない・・・・・・・・
今日・・・・・・今日「だけ」がんばるんだっ・・・・・・・・・・・・！
今日をがんばった者・・・・・・・・・・・
今日をがんばり始めた者にのみ・・・・・
明日が来るんだよ・・・・・・・・・・・！

Jenkinsユーザカンファレンスと直後の第1回福岡Jenkins勉強会も無事終わって、「明日からユーザカンファレンスのレポート書こう」と思ってたうちにお盆休みになってしまってガクゼンとしているikikkoです。こんにちは。

今必死に発表スライドと録画されたやつを聞きながらレポート書いているのですが、レポート書くときにどんな構成でどんなことに気を使って書いているかをちょっとだけ紹介したいと思います。あくまで僕はこんな感じでやってますというだけで、他の人がどうやってるかは知りませんし、これが一番ベストとかも思ってませんので。

ちなみに、今まで書いてきたレポートは、以下のところで掲載させてもらっています。基本は、後述する流れに沿うように書いているので、どなたかの参考になれば。

レポート作成の流れ

レポート用のファイル用意したり、色々下準備（30分）
発表スライドや当日のUstを見ながら、発表の構成要素を洗い出す（1時間〜1時間半 × 発表数）
構成要素を元に、文章として清書する（1時間 × 発表数）
見直し（30分）

こんな感じなので、平日帰宅後だとまあ1週間、週末だと土日作業になってしまってます。もうちょい早く書けるようになりたい気も。

レポートの段落分け

発表者紹介（1文）
写真
発表内容（3~5文）
意見（2~3文）

文章数を↑に揃えようとして、重文・複文が多くなって、1文が複雑になってしまいがちなのは、ちょっとあれです。通常は、1文1文の主語述語が分かりやすいよう単文の方がいいと思うし、他の場所でドキュメント書くときはそうするよう心がけています。

発表内容と意見

発表内容部分では、主観は入れずに事実のみを客観的に説明するようにしています。逆に、意見部分は、個人の意見をちゃんと盛り込むように。

発表内容のところは、どうしても過去形が多くなりがち（〜しました、〜でした）。文末が一緒だと（小学生の夏休みの日記みたいになって）文章が幼稚に見えるので、あの手この手でちょこちょこ変えてるけどちょっとツライ。

意見部分は、レポートで一番大事だと思ってる部分です。発表をなぞるだけのレポートならスライド見たり当日のtwitterとか見てればいいので、それ以上のものを提供できるようにというのは心がけています。もちろん、個人的/主観的な意見ですよというのが分かるように、↑で説明したように段落も分けてます。

あと、意見部分では自分の意見と共に、発表内容では触れなかったけど関連することも積極的に参考情報として入れるようにしています。勉強会参加した人が後からレポート読んだときにも参考になるようにという願いも込めて。

レポートの媒体

前まではWikiに書いていたけど、最近はSphinx。ちなみに、Jenkinsで生成したファイルをBacklogのファイル共有に転送する | Nulab Tech Blogをローカルマシン上で動かしています。

別件でHTML上のドキュメントを直接編集する機会もあったけど、デザインの方に気を取られて文章がなかなか書けない。その点ではWikiの方がまだマシなんだけど、保存のタイミングとかがちょっとあれな感じ。やっぱりSphinxのように、ローカルのテキストファイルで書いておいて適宜保存、きりのいいタイミングでcommit/pushして公開するってのがリズム的にもいい気がしてます。

文章の体裁

そこまで重要視してないけど、体裁的なところはこれぐらいは気をつけてます。

ですます調
名称は氏で統一
リンクは最初だけ貼って、以降同じものが出てきたときは貼ってない