★その他Tips
- 調査依頼があったときのおおまかな進め方
- 書籍「はじめての圏論」で射の合成に使用されている記号
- Qiitaで脚注を表現するとき
- noteでLatex記法を使う
- sasテンプレート
- Latexで矢印を表現するとき(写像の別表現に関しても記載)
- 罫線素片
- Latexに関するメモ
- 圏論に関する外部リンク
- ドキュメント作りにおけるルール整備
調査依頼があったときのおおまかな進め方
- 1. 調査依頼の受領
- 「こんなエラーが出た」「この辺りの仕様はどうなっていますか?」などの調査依頼がチケットとして届く
- 2. 再現性の確認
- もらった情報を元に、まずは依頼者が直面しているエラーや問題が手元で再現するかどうかを試行する。
- 再現できた場合 ... 3.へ進む。
- 再現できなかった場合 ... エラー発生時の状況(実行したコード、画面操作の内容、入力した値、どの環境で実行したかなど)を追加で詳しく連携してもらう。
- もらった情報を元に、まずは依頼者が直面しているエラーや問題が手元で再現するかどうかを試行する。
- 3. 事実の収集
- 処理の流れを考え、「最初のエラーは具体的にどこで発生しているのか」「どこまでは想定通り動いているのか」を明確にする。
- こちら側で追加で収集できるもの(動作ログや開発資料)があれば、収集しておく。
- 4. 調査の実施(原因の仮説を定義し、仮説の検証を行う)
- いろんな側面で原因の仮説を立て、可能性の高いものから動作確認を行い、具体的な発生条件を順に明らかにする。
- <具体的な発生条件の例> 「6桁のときはエラーになるが、7桁の時はエラーにならない」などの切り分け情報
- バリエーション・発想が大事になってくることもあるので、必要に応じてメンバーに相談する。
- いろんな側面で原因の仮説を立て、可能性の高いものから動作確認を行い、具体的な発生条件を順に明らかにする。
- 5. 真因の特定
- 明らかにした発生条件を整理し、エラーや問題に直接的に作用している発生条件を明確にする。
- 必要に応じて、その真因が発生するに至った背景・経緯も可能な範囲で調べる。
- 6. 不具合の修正および報告
- 原因や修正内容を整理し、対応と報告を行う。
- 本番運用などでは「暫定対処」「恒久対処」のように、2段階で対処を行う。(まずは取り急ぎ問題を解決してから、その後の根本的な原因を解消する、といった流れ)
「原因の仮説定義および仮説の検証」のイメージ
- [疑問や課題]どうしてこのようなエラーが出るのか?
- [原因の仮説1] 変数のデータ型が異なっているために処理中の型変換が行えず、エラーとなってしまう。
- [仮説の検証結果1] いいえ。データ型をdouble型で揃えてみても、エラー内容に変化はなかった。
- [得られた事実1] データ型の差異はエラーの原因ではない。
- [仮説の検証結果1] いいえ。データ型をdouble型で揃えてみても、エラー内容に変化はなかった。
- [原因の仮説2] 文字コードがUTF-8ではなく、想定外の入力値となってしまっている。
- ...
- [原因の仮説1] 変数のデータ型が異なっているために処理中の型変換が行えず、エラーとなってしまう。
書籍「はじめての圏論」で射の合成に使用されている記号
⨾
文字コードはU+2A3E。日本語入力モードで2a3eと打ち、F5で変換することで出せる。
https://tex.stackexchange.com/questions/125012/what-is-the-latex-code-for-an-open-semicolon
Latexだと、パッケージを追加すれば出せるみたい。
- mathbbolパッケージ ...
\fcmp - stmaryrdパッケージ ...
\fatsemi
Qiitaで脚注を表現するとき
本文中に次のような文字列を記述することで脚注を表現できます。[^1]
[^1]: 脚注の注釈内容は、このように記述します。
https://blog.qiita.com/105484781374-2/
noteでLatex記法を使う
$${y = x ^ 2}$$のように記載する。
sasテンプレート
関数
<>
Latexで矢印を表現するとき(写像の別表現に関しても記載)
https://mathlandscape.com/latex-arrow/
罫線素片
Latexに関するメモ
よく使うやつ
| 記号 | Latex記法 | 備考 |
|---|---|---|
| → | \to |
|
| ∈ | \in |
集合は元(要素)を含む |
| ∘ | \circ |
関数・射の合成 |
| ∙ | \bullet |
|
| 斜体にしない | \rm{...} |
|
| := | \coloneqq |
定義 |
| ほんのちょっとのスペース | \, |
3/18 em(半角スペースが4/18emくらい) |
mathlandscape.com
- 【LaTeX】矢印(写像,極限,同値)のコマンド107個一覧
- 【LaTeX】集合演算子のコマンド110個一覧
- 【LaTeX】論理記号(否定,かつ,または,任意,存在など)一覧
- 【LaTeX】水平方向の空白(スペース)のコマンド11個
圏論に関する外部リンク
ドキュメント作りにおけるルール整備
文体・文章構造について
- 本文は日本語の「だ・である」調を基本とすること
- 本文において、体言止めは使用しないこと
- 箇条書きによるリストアップ、表内の記載、見出しは例外とする
- 一文には原則として、一つの要件や判断を記載すること
- 一つの行や文に複数の論点を詰め込まず、改行または文章の分割を行うことで小さい文を積み上げ、表現すること
記載内容について
- 主語や実施主体、対象や処理対象がわかる文章にすること
- 例えば「手動入力で保持」のような、曖昧な表現を避ける
- 現行仕様 or 移行後の要件 or 将来構想を区別して記載すること
- ❗️事実と想定、合意事項と提案など 扱いの異なる情報 をしっかり区別すること
- 必須要件は「〜する」「〜しない」など、要否を判断できる表現にすること
- 「適宜」「必要に応じて」「可能な限り」などの曖昧な表現は使用を避け、どうしても使用する場合は条件や判断者を記載すること
Markdown 記法について
- 本文において、強調記法(
**...**)を多用しないこと- 使用する場合は短い項目名やラベルに限定し、文章・事実・値・状態の強調には使用しないこと
- ❗️ひとかたまりのテキストであることを示すために、強調記法を使用しないこと
- 強調記法については、多用すると強調したい部分が強調されなくなってしまうため、一文につき一か所だけを使用することを目安とする
**項目の概要**: 項目の詳細という表現の使用を認めるが、下記に注意すること- 箇条書きの階層表現により概要と詳細を表現できる場合には、箇条書きを優先して使用すること
- 番号付きリストについて、 Markdown の表形式で記載した方が読みやすくなる場合があるため、表形式での記載も検討すること
- 手順に「番号・項目名・詳細」が並ぶ場合などは、表形式が望ましい
- Markdown のプレビューも合わせて確認し、書式が崩れていないことを確認すること
- 具体的には、表が崩れている、不要な水平線がある、意図しない形で見出し表現になっているなど
本文における記号の使用について
- ❗️読者に解釈を委ねるような記号・表現が使用されていないこと
- 具体的には「X→Yマッピング」といった抽象的すぎる記載を避け、「XからYへの機能マッピング」といった具体的な表現を使用する
- 箇条書きリストの導入文の末尾にコロン
:は使用せず、通常の文章および句点を使用すること - 必要に応じて、強調記法(
**...**)ではなくかぎ括弧「...」により強調を行うことを認める
用語・キーワードの使用について
- 全体を通して、表記揺れがないこと(
ユーザvsユーザーや、Testingvstestingなど)- 英大文字・英小文字の違いや、半角スペースありなしなどにも留意する
- 製品の正式名称、コード、パラメータ名、ファイルパス、URL、引用文に含まれるスペースは、機械的な置換を行わないこと
- ❗️製品固有のキーワードについて、説明もなく突然現れたキーワードがないこと
- 製品固有のキーワードについて、表記間違いが存在しないこと
文章の半角スペースの取り扱い
- 「英単語または英語の固有名詞」と「日本語」の間には、半角スペースを1ついれること
- 英略語と日本語の間には、半角スペースを入れないこと
- 英略語とは、
AWS/GCP/MQなど、全大文字で表記する略称を指す
- 英略語とは、
- 複数の英略語で構成される正式名称内のスペースは維持すること(
AWS IAMなど) - 数値、数量を表す接頭辞、単位および日本語の間には、半角スペースを入れないこと
1,234 kmではなく、1,234kmのように表記する
| 内容 | 半角スペース | 記載例 |
|---|---|---|
| 英単語または英語の固有名詞 と 日本語 の間 | 入れる | Web アプリケーション / Python コード |
| 英略語 と 日本語の間 | 入れない | API認証 / SSH接続 / AWSアカウント |
| 複数の英略語で構成される、正式名称内のスペース | 入れる | REST API認証 / AWS IAMロール |
| 数値、数量を表す接頭辞、単位 と 日本語 の間 | 入れない | 2環境 / 約80% / 2027年3月 / 1,234km |
修正時の対応
- 単語の表記揺れに関する指摘を受けた際、指摘箇所だけでなくファイルを横断的に修正できていること
- ファイル名や章番号を変更した場合は、目次だけでなく本文リンクや参照情報なども同時に更新すること
その他ルール
- 行末に不要な空白または全角空白を残さないこと
- インデントにはタブを使用せず、半角空白を使用すること
- 見出しの末尾に句点、コロンなどの不要な記号をつけないこと
- Markdownファイルの末尾は空行で終わっていること
