コンテンツにスキップ

本講義の基本的な情報

  • 講義日：毎週月曜日 3限目
  • 担当：宮島 敬明
  • 取得単位数：2

教科書と参考書

目標

「はじめに」より 技術文章では、読み手に推測を要求することがあってはなりません。 技術文章では分かりやすい文章、つまりは読み手に誤解されない文章を記します。 そのためには、論理を組み立て、語句の意味を正しく用いる必要があります。 つまりは自分の獲得した知識を理論的に記すのです。 どう書けばよいのだろうと悩んでいるだけでは文章は上達しません、とにかく文字にします。 そして思いつく限りを文字に変換したら、それを読み、文章は必要な情報を表しているか？説明はきちんと順序を追っているかを考えます。 これが論理です。同時に分をチェックします。 手話何か主語と述語はねじれていないか述語を羅列していないかなど。 自分で書いた文を第三者の目で見ながら改良します。 文章表現のスキルを学べば、文章は書けるようになります。 主張することは何かをはっきりさせて、それを論理立てることを意識しましょう。

担当

  • [第 1 回] みやじま
  • [第 2 回]
  • [第 3 回]
  • [第 4 回]
  • [第 5 回]
  • [第 6 回]
  • [第 7 回]
  • [第 8 回]
  • [第 9 回]

輪講資料で注意すべきこと

  • 自分が大切だと思った要点をまとめること
  • 先輩の輪講資料を参考にして、図を描くことに注力すること
  • 先輩の輪講資料を参考にしてもOKですが、コピペは禁止
  • 教科書の全文をコピペする必要はない。例えば、教科書に載っている事例は、輪講資料に載せる必要は必ずしもない
  • 分かりやすいように、要点を列挙したり、教科書の文章をまとめ直したりすること
  • 5行以上の文章は、箇条書きなどに構成しなおす（NEW!）
  • 例えば、以下のような形です
    1. 図を描いて説明する。ノートに手書きしたものを写真に撮る形でもOKです
    2. 文章から重要な部分を抜き出して、箇条書きにする
    3. 重要な部分を太字にする
  • 時間内に説明できることを心がけること。例えば、教科書に載っている事例を、輪講中に説明する必要は必ずしもない

コードの説明をする時は、以下の流れで説明してね

  • コードの挙動のイメージを説明する。ここでは、細かい説明はまだいらない
  • コードの処理の大まかな説明をする。関数A->B->C
  • 重要そうな関数の説明を詳細にする。関数Aの引数とか、処理の意味とか

輪講資料の作り方

資料を作成する時は、GitLabとMarkdownを使います。
具体的には、ゼミの資料ページをcloneして、自分の担当する章のbranchを作って、docsディレクトリの下の担当の章のディレクトリで作業をして、pushしてマージリクエストをする流れになります。 資料自体はMarkdownで書くこと。

GitLabプロジェクトへのメンバー追加とclone

みなさんを、輪講のGitLabプロジェクト にみなさんをDeveloperとして登録します。
なので、GitLab.comのアカウントを私に教えてください。もし作っていない人は作ってね。 また、以下のコマンドでリポジトリをcloneしてください。 

git clone git@gitlab.com:t3840/2025_spring_b4_grad_research_1_reading_class_2.git

作業開始

リポジトリのdocsディレクトリの内部で作業をします。 また、自分の作業用ブランチを必ず切ってください。 mainブランチは保護されているので、直接コミットができません。 たとえば、第2章を担当する人は、chapter2ブランチを作成した後、./docs/chapter2/{chapter2.md,figures/}以下で作業をしてください。

資料作成

cloneできたら資料を作ります。 今回は、markdownからwebページを作成する際には、mkdocsというものを使っています。 Linux環境でmkdocsをインストールして、やってみてください。1

  • 箇条書きを注意してください。GitLab上の見た目とmkdocsでレンダリングされる結果は違うよ
  • 手元のUbuntuなどで make build などとして出来を確認してください
  • 数式を囲むときは、$ではなくて、$`と`$で囲むので注意してください
  • 画像のサイズ変更は{: style="height:300px"}とかやると変更できます
  • 一部使えない拡張があるかもしれません
  • mkdocsの環境構築がつらい、という人はGitLab.comのWebインターフェイスで書くこともできます

資料作成をマージ

資料が完成したらpushして、 マージリクエストのページ から自分のブランチをmainブランチにマージするリクエストを作成してください。 また、みやじまにSlackなどでマージしてほしい旨を連絡してください。 少しするとページが更新されるますので、できあがりを確認してください。

なお、コミットすると自動的にCIが走る設定ですが、自分のGitLabアカウントでクレカの登録が必要です。 これが原因でCIが失敗になりますが、失敗でも構いません。 課金はされないので、登録できる人はしてください。 CIの結果は、 プロジェクトページのCIの部分 で見られます。

ライセンス

Creative Commons — 表示 - 非営利 4.0 国際 — CC BY-NC 4.0

  1. https://zenn.dev/mebiusbox/articles/81d977a72cee01 ↩