はじめに

「エンジニアだから文章書けなくてもいいや～」
なんてことを言う人は…あまりいないと思いますが。
「エンジニアなのにこんなたくさん文章書かされるの？」
と思うことはあるかと思います。

仕様書だったり、報告書だったり、手順書だったり…。
チームのため、あるいは業務効率化のために、情報共有は欠かせません。
「読者や⽬的に合わせて、技術をわかりやすく伝えること」
これがテクニカルライティングの基本です。

情報を伝えるために大切なこと

1. 伝える情報を整理する
2. ⾒出し単位でアウトラインを作る
3. 段落単位で⽂章の⾻組みを作る
4. わかりやすく、簡潔な⽂章で書く

大切なことはこの4つです。
だいたい、たいていの人は細部まで読みません。業務でテキストを読む場合、必要なことは「情報を得ること」であって「読むこと」ではないからです。

1. 伝える情報を整理する

「誰が読むのか」「どういう情報を求めているのか」この2点を常に頭に置いておきましょう。
基本的には、伝える情報を階層構造として整理することが大切です。
全体から部分へ、概要から具体例へ、順を追って記載していくとよいでしょう。

技術書を例にとると
まずタイトルがあって、目次があって、章立てされていて、項目ごとに内容が分かれています。
WEBページでも、まずTOPがあり、カテゴライズされたページがあり、さらにページごとに内容が分かれています。TOPを見れば何についてのページなのかわかるようになっています。
順に説明していくことが分かりやすさにつながります。

また、読み手によって持っている知識や欲しい情報は様々です。
途中から読んでも理解できてしまう人もいれば、先頭から読まないと分からないという人もいるでしょう。
急いでいるなら、欲しい情報だけ知りたい、ということがあるかもしれません。
どこに何が書いてあるかがわかるよう、適切なタイトルと⾒出しを付けることが大事です。

2. ⾒出し単位でアウトラインを作る

アウトラインとは
・ものごとの概略や大筋
・ドキュメントにおけるアウトラインとは、章・節・項などの⾒出しを階層的に設定し表示したもの

このアウトラインを作ることで、
・説明の流れが読み手にも理解しやすくなる。
・必要とする情報がどこに書かれているか探しやすくする。
という効果があります。

アウトラインを作るためにはまず「情報を適切に分解すること」が必要です。
きれいに分解する必要はありません。読み手の目的に合わせて分解することが大切です。
そして、分解した要素の中から、見出しをつけなくてはいけない要素を選び、見出しを決めていきましょう。

3. 段落単位で⽂章の⾻組みを作る

文章の骨組みを作るときに、大事なことは

• ひとつのドキュメントで、1つのテーマ
• ひとつの見出しで、1つのサブテーマ
• ひとつの段落でひとつのトピック

この3つです。
ドキュメント全体を見た場合、テーマがあっちへ行ったりこっちへ行ったりしていたら分かりにくいですよね。
おなじように、ひとつの見出しに別のことが2つ以上書かれていたら混乱してしまいます。
また、だらだらと長く書いても読み手は疲れてしまいます。紙で出力するものなら、ひとつの段落はせいぜい4～8文程度。WEB媒体なら2～4文程度が目安です。
長すぎると読みづらくなりますし、逆に短すぎても言葉が足りなくなってしまうので気をつけましょう。
文章を書き始める前に、段落単位で文章の構成を組んでおくことが大事です。

トピックを意識することで、
読み手は
　1．順序だてて話題が進むため、理解しやすくなる
　2．知っていることがあれば、段落単位で読み飛ばせる
書き手は
　1．書くべき内容が決まっているため書きやすくなる
　2．内容の過不足を把握しやすくなる
といったメリットがあります。

4. わかりやすく、簡潔な⽂章で書く

書く時の心構えとして大事なことは、
・常に読み手を意識しながら書く
　どんな人が読むのか
　どんな情報を探すのか
　どこで読むのか
　…etc.
・簡潔に書く

この2つです。
文章を書くときの大前提に「一文一意/一文一義（いちぶん-いちい/いちぎ）」があります。
ひとつの文章では、ひとつの事柄だけを説明する。という意味ですね。

たとえば、製品マニュアルを書くことになった場合、
「商品の蓋を開けると、青いスイッチがあり、その隣に赤いボタンがあるので、そのボタンを押して表示を確認してから次に青いスイッチを入れて…」
と書かれていたらどう思いますか？
最初に何をすればいいの？これは何のマニュアル？となってしまいます。
なので、ひとつの文は長すぎず短すぎず、なるべく100文字以内に納めるようにしましょう。

また、最初のほうにも書きましたが、
たいていの人は細部まで読みません。業務でテキストを読む場合、必要なことは「情報を得ること」であって「読むこと」ではないからです。

短文のSNS投稿ツールX/Twitterや、Instagramなどでもよく話が大幅に逸れて炎上していることがあります。
X/Twitterなんて、課金しなければ全角140文字しか投稿できないのに、自分に都合のいい部分だけ切り取って読む人が多いので炎上しやすいんです…。

ビジネスの世界はそこまで揉めることはありませんが、相手の負担を減らし、伝えたいことが正しく伝わるためにも
・重要なことから書く（まず主張、そのあとに理由を書く）
・読み手の視点で書く
・能動態と受動態を使い分ける
・読点を適切に打つ
・並列の情報には箇条書きを使う
・できるだけ具体的に書く
・肯定形で書く（特に⼆重否定は使わない）
これらを守って書くようにしましょう。

以下に、読みづらい文章と読みやすいとされる文章の例を挙げておきます。
どう違うのか、読んでみてください。

さいごに

このほかにも「てにをはに気を付ける」、「係り受けの関係に気を付ける」、「同じ助詞が連続しないように気を付ける」、「ねじれ文に気を付ける」など、文章を書く上で気を付けるべき点はたくさんあります。

文章力をアップするコツは、いろんな本をたくさん読むこと。
仕様書やビジネス文書だけでなく、小説や論文など、いろんな種類の本を読み、アウトプットすることで文章力もアップします。

最近ではAI技術が急速に発展し、ChatGPTなどの人工知能や機械学習を使った開発が注目されています。
そこで今回は、機械学習に興味はあるけど詳しくわからないという人に向けて、機械学習の基礎知識や実際に開発する際の基本的な手順を説明します。

機械学習とは

機械学習はコンピュータがデータから学習し、予測や意思決定を行う能力を持つ技術です。
データを解析し、パターンや関係性を自動的に学習して、未知のデータに対して予測や分類を行うことができます。

AIと機械学習の違い

AI（人工知能）は、コンピュータに人間の知的な能力を持たせる技術を指し、機械学習はAIの一部でありデータからパターンを学習して予測や意思決定を行う手法です。
AIには機械学習以外の手法やルールベースのアプローチも含んでおり、人間の知的な能力を持たせるため幅広い技術を使用しています。

機械学習でできること

機械学習では画像認識や音声認識、自然言語処理、レコメンドシステム、不正検知、予測分析などの様々なタスクをこなすことが可能です。

機械学習の種類

機械学習は一般的に「教師あり学習」「教師なし学習」「強化学習」と呼ばれる3つの分類に分けられます。

教師あり学習

データとそれに対応するラベル(正解値)を与えることで、モデルはパターンや関連性を学習し、新たなデータに対して予測や分類を行います。

教師なし学習

ラベルのないデータを用いてパターンや構造を見つける手法です。データ自体の特徴や相関関係を抽出し、クラスタリングや次元削減などのタスクを実行します。

強化学習

強化学習は、コンピューターがゲームや問題を解く方法を学ぶ方法です。コンピューターは、行動を選択し、それによって得られる報酬を最大化するために学習します。
例えば、オセロではどこに石を置くかを選択し、それによってとれた石の数を報酬とします。この報酬を元に繰り返し戦略を改善していくことで精度を強化することができます。

機械学習を使用した開発の手順

ここでは教師あり学習を例に、機械学習を使った開発を行う場合の手順を説明します。

データセットの準備

機械学習では、学習のためにデータが必要です。データセットは入力データとそれに対応する正解データ（ラベル）から構成されます。

この準備の工程が、機械学習においては非常に重要で大変な作業となります。例えば、分類モデルではクラス（犬or猫）ごとに約1000~10000枚の画像を必要とします。膨大なデータを集めることは容易ではないため、枚数が足りない場合は画像の回転や拡大縮小、反転などを用いてデータを水増しして作成します。

モデルの選択と学習

回帰モデル、分類モデルともに複数の手法があるので適したモデルを選択し、準備したデータセットを使用してモデルに学習させます。
回帰モデルの主な例として線形回帰や決定木（XGBoost, LightGBM）など、分類モデルにはSVM(サポートベクタマシン)、ロジスティック回帰、k近傍法などがあります。

予測

学習が完了したモデルを使用して、新しいデータの予測を行います。予測結果は、分類問題の場合はクラスのラベル、回帰問題の場合は数値として表現されます。

モデルの評価

作成したモデルに対し、予測結果の正確さや性能を評価します。一般的な評価指標には、分類モデルでは正解率や適合率、回帰モデルではRMSEや決定係数と呼ばれる指標が使用されます。

おわりに

今回は、機械学習の基礎知識や開発手順を説明しました。この記事を通じて少しでも機械学習のイメージが掴めると嬉しいです。最後まで読んでいただきありがとうございました。

はじめに

本記事ではLinuxコマンド「|」(パイプ)と「;」(セミコロン)についてまとめます。
コマンドの挙動で勘違いしていた部分があったので、調べることにしました。

1. コマンド「｜」(パイプ)

ここでは、コマンド「｜」(パイプ)について、実行例などを基に説明します。

1-1. コマンド「｜」(パイプ)とは

パイプとは、Linuxコマンドの標準出力結果を次のコマンドに渡すために使用されるコマンドです。
パイプを使用することで複数のコマンドを1つのプログラムのように動かすことができます。
パイプの正式名称は「パイプライン」と呼ばれます。

1-2. コマンド「｜」(パイプ)の書式

コマンド「｜」(パイプ)の書式は以下の通りです。

$ (command_1) | (command_2) | … | (command_n)

1-3. 実行例

「｜」(パイプ)でよく使用されるパターンとして、標準出力の内容を操作することが多いです。
実際に、このコマンドが使用される実行例を紹介します。

例1:「grep」コマンドとの組み合わせ

「grep」は、文字列を検索するLinuxコマンドです。

• テキストファイルから特定の文字列で「grep」を行う

①テキストの中身を表示する

[C:\Users\sp-taro]$ cat sample1.txt

aaaaa
bbbbb
ccccc

②文字列「aaaaa」でgrepを行う

[C:\Users\sp-taro]$ cat sample1.txt | grep aaaaa

aaaaa

　⇒条件に一致する文字列が出力されます。

③文字列「abc」でgrepを行う

[C:\Users\sp-taro]$ cat sample1.txt | grep abc

[C:\Users\sp-taro]$

　⇒条件に一致する文字列がないので、何も出力されませんでした。

例2:「tee」コマンドとの組み合わせ

「tee」コマンドは、標準出力の結果をファイルに出力できるコマンドです。

● カレントディレクトリに指定した文字列を含むファイル名を別ファイルに書き出す

①カレントディレクトリに存在するファイルを確認する

[C:\Users\sp-taro]$ ls -l

total 8
-rw-rw-r-- 1 dba dba 19 Aug 22 19:26 sample1.txt
-rw-rw-r-- 1 dba dba 19 Aug 22 19:26 sample2.txt
-rw-rw-r-- 1 dba dba  0 Aug 22 20:15 test1.txt
-rw-rw-r-- 1 dba dba  0 Aug 22 20:15 test2.txt

②「find」コマンドを使用し、指定した文字列を含むファイル名を別ファイルに出力する

[C:\Users\sp-taro]$ find test* | tee sample3.txt

test1.txt
test2.txt

③カレントディレクトリに存在するファイルを確認する。

[C:\Users\sp-taro]$ ls -l

total 12
-rw-rw-r-- 1 dba dba 19 Aug 22 19:26 sample1.txt
-rw-rw-r-- 1 dba dba 19 Aug 22 19:26 sample2.txt
-rw-rw-r-- 1 dba dba 20 Aug 22 20:21 sample3.txt ←新規作成された
-rw-rw-r-- 1 dba dba  0 Aug 22 20:15 test1.txt
-rw-rw-r-- 1 dba dba  0 Aug 22 20:15 test2.txt

　⇒新たにsample3.txtというファイルが作成されました。

④sample3.txtの中身を確認する

[C:\Users\sp-taro]$ cat sample3.txt

test1.txt
test2.txt

⇒「find」コマンドで指定した文字列を含むファイル名が書き出されています。

2. コマンド「;」(セミコロン)について

ここでは、コマンド「;」(セミコロン)について、実行例などを基に説明します。

2-1. コマンド「;」(セミコロン)とは

セミコロンとは、複数のコマンドを続けて実行する際に使用されるLinuxコマンドです。
コマンドが終了してから次のコマンドが実行されます。

2-2. コマンド「;」(セミコロン)の書式

コマンド「；」(セミコロン)の書式は以下の通りです。

$ (command_1) ; (command_2) ; … ; (command_n)

2-3. 実行例

「；」(セミコロン)は、単純にコマンドを複数続けて実行するだけなので、よく使われるパターンみたいなものはなさそうです。
なので、複数コマンドを実行したときにコマンドが終わるまで次のコマンドが待機されるか確認してみたいと思います。

• 「時刻取得」→「30秒待機」→「時刻取得」を1コマンドで実行する。

[C:\Users\sp-taro]$ date ; sleep 30s ; date

Thu Aug 25 18:25:20 JST 2022　←コマンド1実行結果
Thu Aug 25 18:25:50 JST 2022　←コマンド3実行結果

　⇒コマンド1で時刻を取得してから、コマンド3で再度時刻を取得するまで30秒待機していることがわかります。

3. それぞれのコマンドの挙動の違い

ここでは、「はじめに」
で記載したコマンドの挙動で勘違いしていた部分についてまとめます。

やろうとしたこと

コマンド1で環境変数に値を設定し、コマンド2で設定した変数の値を使う。
２つのコマンドはパイプでつなげる。

実行してみた

export VAR=sample | echo $VAR

[C:\Users\sp-taro]$ export VAR=sample | echo $VAR

⇒結果、何も表示されませんでした。

セミコロン「;」で実行してみた

export VAR=sample ; echo $VAR

[C:\Users\sp-taro]$ export VAR=sample ; echo $VAR
sample

　⇒ちゃんと表示されました。

上記結果より、
セミコロンはコマンドを連続で実行するのに対し、パイプは標準出力された値を次のコマンドに渡すだけであって、実際にコマンドが実行されているわけではなさそうです。

改めてですが、パイプは「標準出力した結果を次のコマンドに渡す」処理です。
なので今回のexportのように、出力されるものがない場合は次のコマンドに渡す値はありません。
パイプとして値を渡していないのはわかりますが、exportが実行されていれば内部的には変数が設定されるので、値が表示される想定でした。

そもそもセミコロンで実行すれば何も問題なかったですが、、、
こういう挙動をする、ということで気を付けないといけませんね。

さいごに

Linuxコマンドのパイプとセミコロンと、それぞれのコマンドの挙動の違いについてまとめました。
他にもLinuxにはたくさんのコマンドがあるので、興味があれば是非調べてみてください。
ご覧いただきありがとうございました。