docs: add a writing guide for students by toshi0806 · Pull Request #55 · smkwlab/smkwlab.github.io

toshi0806 · 2026-11-12T16:55:17Z

概要

論文やレポートを書くときの手引きを、writing/ に置きます。週報、各種レポート、卒論・修論、学会の原稿のどれにも当てはまる内容です。

第 1 版は、これまでの添削で先生が残したコメントの多い 25 項目に絞りました。管理は smkwlab/thesis-review-rules#17 で行います。

変更内容

writing/index.md を追加しました。章立ては次のとおりです。
1. 論理と説明
2. 段落
3. 文
4. 語
5. 図表と文献
6. 提出前のチェックリスト
各項目は、次の 4 つで書いています。例はすべて架空です。
- なぜ
- 悪い例
- 良い例
- 確かめる問い
各節には {#causality} のような固定のアンカーを付けました。添削のコメントから …/writing/#causality の形でリンクするためです。
トップページ(index.md)には、まだリンクを張っていません。張り方は、この PR で決めます。

確認すること

プレビューで表示を確かめる(見出しのアンカー、引用ブロック、チェックリスト)。

https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

The first edition covers the 25 points the review comments raise most often, grouped by unit of writing, with a checklist of mechanical checks to run before sending a PR. Every example is invented. Claude-Session: https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions

全体として、学生向けの論文執筆ガイドとして非常によく整理されており、具体的な悪い例・良い例が分かりやすく示されています。以下にいくつか気になる点を挙げます。

github-actions · 2026-11-12T16:55:51Z

+
+**悪い例**
+
+> TCP はデータを速く届けるためのプロトコルである。近年、若者の読書離れが進んでいる。


⚠️ [MEDIUM] 5.2節の悪い例で「TCP はデータを速く届けるためのプロトコルである」と書かれていますが、TCPは信頼性を重視するプロトコルであり、「速く届ける」という説明はUDPの特徴に近いです。悪い例として意図的に誤った説明を載せているとしても、学生がこの文を正しい情報として誤読するリスクがあります。良い例の説明（「データの到達確認と再送によって信頼性のある通信を提供する」）と対比させるためであれば、悪い例の問題点が「出典がない」ことだけでなく「内容も誤っている」ことになり、混乱を招く可能性があります。悪い例の文を「TCP はデータを確実に届けるためのプロトコルである。」のように、内容は正しいが出典がない例に修正することを検討してください。

対応しました(8d05674)。悪い例を「TCP は、データを確実に届けるためのプロトコルである。」にしました。内容は正しく、出典がないことだけが問題の例になっています。

github-actions · 2026-11-12T16:55:51Z

+PR を送る前に、次のことを確かめてください。
+どれも機械的に見つけられます。エディタの検索と、textlint の警告を使ってください。
+
+- [ ] **番号を手で書いていない。** 図表、章、節の番号は `\label` と `\ref` で書く。「以下の図」「上の表」のように位置で指さない。


⚠️ [MEDIUM] チェックリストの項目（6章）はLaTeX固有の記法（\label、\ref、\cite、[htbp]、[H]など）に特化して書かれています。一方、冒頭では「週報、各種レポート、卒業論文、修士論文、学会の原稿のどれにも当てはまります」と述べています。週報やMarkdownで書くレポートにはLaTeXの記法は関係しないため、チェックリストの対象読者が限定されることを明示するか（例：「LaTeXで書く場合」という注記を追加する）、または非LaTeX向けの項目も追加することを検討してください。

対応しました(8d05674)。チェックリストの冒頭に「項目の多くは、LaTeX で書く場合のものです。」と書き加えました。

さらに直しました(fc5d335)。注記を足すのではなく、チェックリストを「どの形式でも」と「LaTeX で書く場合」に分けています。

github-actions · 2026-11-12T16:55:51Z

+
+**確かめる問い:** この「確認する」のは誰ですか。画面や機能が、人の動作をしていませんか。
+
+### 3.2 助詞を選ぶ {#particle}


ℹ️ [LOW] 3.2節の「は」「主要な」「など」についての説明が、助詞の誤用（「を」と「に」の取り違え）という主題から少し外れています。節タイトルが「助詞を選ぶ」であるのに、「は」や「主要な」は助詞ではありません。節タイトルを「助詞・限定表現を選ぶ」などに変えるか、「は」「主要な」「など」については別の節（例えば1.7節「主張の強さを根拠に合わせる」や4.5節「ぼかした語を具体的にする」）に統合することを検討してください。

対応しました(8d05674)。見出しを「助詞と限定の語を選ぶ」にしました。アンカー #particle は変えていません。対応表(smkwlab/thesis-review-rules#18、19fb17b)の節名もそろえました。

github-actions · 2026-11-12T16:56:14Z

PR Preview Action v1.8.2
🚀 View preview at https://smkwlab.github.io/pr-preview/pr-55/
Built to branch `gh-pages` at 2026-11-12 17:04 UTC. Preview will be ready when the GitHub Pages deployment is complete.

…list scope (smkwlab/thesis-review-rules#17) Claude-Session: https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions

全体として、学生向けの論文執筆ガイドとして非常によく整理されており、具体的な悪い例・良い例が示されていて実用的です。以下に気になった点を挙げます。

github-actions · 2026-11-12T17:00:18Z

+**良い例**
+
+> 位置の補正には XYZ(Extended Yard Zoning)を用いた。XYZ は地図を格子に区切って座標を補正する手法である[1]。
+> 貸出台帳は、図書室が利用者ごとの貸出履歴を記録している表である。本研究ではこれを移行した。


⚠️ [MEDIUM] 良い例の引用ブロック内で > が2行にわたっていますが、Markdown の引用ブロックでは空行を挟まずに連続した > を使うと1つの引用ブロックとして表示されます。ただし、意図的に2つの別々の段落として見せたい場合は `>

のように空行を>` で埋める必要があります。現状の書き方（空行なしで連続）は意図通りに表示されるか、プレビューで確認してください。

据え置きます。1 つの引用ブロックとして続けて見せるのが意図どおりです。プレビュー(pr-55/writing/)でも、良い例が 1 つの引用ブロックに表示されることを確かめました。

github-actions · 2026-11-12T17:00:19Z

+- [ ] **英字の語と和文の間に空白がある。** 例: `設定は timeout で指定する`。空白がないと LaTeX がそこで改行できず、行が右の余白にはみ出します。数字、句読点、括弧の隣、`\ref` と `\cite` の前には要りません。
+- [ ] **誤字脱字がない。** 助詞の重複(「をを」)、送り仮名の不揃い、製品名の綴りと大文字小文字を確かめる。差分だけでも読み返してください。
+- [ ] **全角と半角が正しい。** 全角空白、全角の英数字、「,」と「、」の混在がない。`\cite` は句点の前に置く。
+- [ ] **ソースは 1 文ごとに改行している。** `_`、`%`、`$`、`~` をエスケープしている(例: `book\_id`)。


ℹ️ [LOW] チェックリストの項目に「ソースは 1 文ごとに改行している」とありますが、これは LaTeX 固有の話題というより、このリポジトリの運用ルール（textlint や Git diff の読みやすさ）に関わる重要な規則です。「項目の多くは、LaTeX で書く場合のものです」という前置きがあるため、この項目が LaTeX 限定に見えてしまう可能性があります。Markdown で書く場合にも同様のルールが適用されるなら、その旨を明記するか、LaTeX 固有の項目とそれ以外を分けて示すと、読者の混乱を防げます。

据え置きます。この項目は、LaTeX のソースについての規則です(エスケープの例も LaTeX のもの)。研究室で書く文書は LaTeX のテンプレートから作るので、LaTeX 限定に読めても困りません。

先ほどの据え置きを取り消し、対応しました(fc5d335)。「研究室の文書は LaTeX のテンプレートから作る」と書いたのは誤りで、ISE レポートは HTML で書きます。チェックリストを「どの形式でも」と「LaTeX で書く場合」に分けました。1 文ごとの改行は「どの形式でも」に移し、理由を PR の差分の読みやすさとしました。エスケープは「LaTeX で書く場合」に残しています。

github-actions · 2026-11-12T17:00:19Z

+
+**良い例**
+
+> 「公開サービスへのトラフィックの解析」[3]では、到達するトラフィックを分析している。(文献欄: A. Author, "Sample Protocol", RFC 0000, January 2000)


ℹ️ [LOW] 5.3 節の悪い例で 山田氏は と書いており、直後の説明で「著者に敬称を付けず」と指摘しています。この対応は明確で良いのですが、良い例の文献欄に A. Author, "Sample Protocol", RFC 0000, January 2000 という架空の RFC を使っています。RFC の書誌形式としては著者名・タイトル・番号・年月が含まれており適切ですが、学術論文（会議・ジャーナル）の書誌形式の例も1つ添えると、より幅広いケースをカバーできます。

据え置きます。第 1 版は、添削で多く指摘してきた点に絞っています。論文の書誌の形式は、学会やテンプレートの文献スタイルで決まるので、この手引きでは扱いません。

toshi0806 · 2026-11-12T17:01:22Z

AI レビューの指摘 6 件への対応です。

対応した 3 件(8d05674):
- 5.2 の悪い例を、内容は正しく出典がないだけの文にしました。
- チェックリストの冒頭に、LaTeX で書く場合の項目が多いことを書き加えました。
- 3.2 の見出しを「助詞と限定の語を選ぶ」にしました。
据え置いた 3 件:
- 引用ブロックの表示は、プレビューで確かめてあり、意図どおりです。
- ソースの改行の規則は LaTeX のものです。
- 論文の書誌の形式は、第 1 版の範囲外としました。

プレビューでは、31 個のアンカーがすべて生成されていること、引用ブロックとチェックリストが表示されることを確かめました。

https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

…thesis-review-rules#17) The ISE report is written in HTML, so only the LaTeX items are LaTeX-specific. Claude-Session: https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions

全体として、学生向けの論文執筆ガイドとして非常によく整理されており、具体的な悪い例・良い例が分かりやすく示されています。以下に気になった点を挙げます。

github-actions · 2026-11-12T17:04:56Z

+**良い例**
+
+> 位置の補正には XYZ(Extended Yard Zoning)を用いた。XYZ は地図を格子に区切って座標を補正する手法である[1]。
+> 貸出台帳は、図書室が利用者ごとの貸出履歴を記録している表である。本研究ではこれを移行した。


⚠️ [MEDIUM] 良い例の引用ブロック内で > が2行にわたっていますが、Markdownの引用ブロックでは空行を挟まずに連続した > を使うと1つの引用ブロックとして表示されます。ただし、意図的に2つの段落を1つの引用ブロック内に入れたい場合は > だけの行（空行の代わり）を挟む必要があります。現状の書き方だと、レンダリング環境によっては2つの別々の引用ブロックとして表示される可能性があります。意図した表示になっているかプレビューで確認してください。

据え置きます。前の同じ指摘(r4553614565)と同じです。表示は、この site の Jekyll(kramdown)のプレビューで、1 つの引用ブロックになることを確かめました。

github-actions · 2026-11-12T17:04:56Z

+
+**良い例**
+
+> 位置の補正には XYZ(Extended Yard Zoning)を用いた。XYZ は地図を格子に区切って座標を補正する手法である[1]。


ℹ️ [LOW] 1.3節の良い例で [1] という文献番号が使われていますが、この手引き自体には文献リストが存在しません。架空の例であることは冒頭に書かれていますが、[1] [2] [3] のような番号が複数の節（1.3、5.2、5.3）に登場するため、読者が「この文献はどこにあるのか」と混乱する可能性があります。例えば [文献番号] や [参考文献] のような表記にするか、「※文献番号は架空」と注記を加えることを検討してください。

据え置きます。例文は、論文の本文を切り出したものとして書いています。[1] は、組み上がった論文で引用がどう見えるかを示しているだけで、この手引きの文献を指すものではありません。冒頭で、例が架空であることも断っています。

github-actions · 2026-11-12T17:04:56Z

+
+**悪い例**
+
+> 山田氏は、到達するトラフィックを分析している。(文献欄: https://example.org/rfc0000)


ℹ️ [LOW] 5.3節の悪い例で「山田氏」という実在しそうな人名が使われています。冒頭に「例はすべて架空のものです」と明記されているので問題は少ないですが、他の例と同様に架空性がより明確な表現（例：「著者名氏」や「田中氏」など）に統一するか、あるいはそのままでも問題ないか確認してください。また、良い例の A. Author は英語表記であり、日本語の論文執筆ガイドとして文献欄の書き方を示す際に、日本語著者名の例も併記するとより実用的です。

据え置きます。「山田氏」は仮の名前としてよく使われる名前で、架空であることは冒頭に書いています。良い例の文献欄は、悪い例の URL だけの書き方と対比するためのもので、ここで示したいのは書誌の要素がそろっていることです。表記の言語は問題にしていません。

toshi0806 · 2026-11-12T17:05:55Z

追加の対応です。

ISE レポートは HTML で書くので、チェックリストを「どの形式でも」と「LaTeX で書く場合」に分けました(fc5d335)。先に「研究室の文書は LaTeX」とした据え置きは、取り消しています。
5.3 の \cite は「引用(LaTeX なら \cite)」としました。
再レビューで届いた 3 件(引用ブロックの表示、例文の [1]、例の人名)は、根拠を添えて据え置きました。
プレビューでは、#checklist-common と #checklist-latex が生成されていることを確かめました。

https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions Bot reviewed Nov 12, 2026

View reviewed changes

docs: fix the writing guide's TCP example, particle heading and check…

8d05674

…list scope (smkwlab/thesis-review-rules#17) Claude-Session: https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions Bot reviewed Nov 12, 2026

View reviewed changes

docs: split the checklist into common and LaTeX-only checks (smkwlab/…

fc5d335

…thesis-review-rules#17) The ISE report is written in HTML, so only the LaTeX items are LaTeX-specific. Claude-Session: https://claude.ai/code/session_01J159SiM9hhWoPD2gxwey97

github-actions Bot reviewed Nov 12, 2026

View reviewed changes


		悪い例

		> TCP はデータを速く届けるためのプロトコルである。近年、若者の読書離れが進んでいる。


		確かめる問い: この「確認する」のは誰ですか。画面や機能が、人の動作をしていませんか。

		### 3.2 助詞を選ぶ {#particle}


		良い例

		> 「公開サービスへのトラフィックの解析」[3]では、到達するトラフィックを分析している。(文献欄: A. Author, "Sample Protocol", RFC 0000, January 2000)


		良い例

		> 位置の補正には XYZ(Extended Yard Zoning)を用いた。XYZ は地図を格子に区切って座標を補正する手法である[1]。


		悪い例

		> 山田氏は、到達するトラフィックを分析している。(文献欄: https://example.org/rfc0000)

Conversation

toshi0806 commented Nov 12, 2026

概要

変更内容

確認すること

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-11-12 17:04 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toshi0806 commented Nov 12, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Nov 12, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toshi0806 commented Nov 12, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

github-actions Bot commented Nov 12, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-11-12 17:04 UTC.
Preview will be ready when the GitHub Pages deployment is complete.