ここは誰？あなたはどこ？
aKuad と申します。興味関心ごとやステータスをざっと挙げると･･･
- ハードウェア、ソフトウェア共に、コンピュータ系のことはほとんど好き。自作PCも興味、サーバ関係にも興味、業務用機材は無限に見ていられるくらい好き。オーディオにも興味。いつかスピーカー自作もしてみたい。
- 一番の好み・得意は、コーディング系のこと。これまでである程度いじくった言語は、「C, HTML & CSS & JavaScript, SHシェルスクリプト」。それから、一応「Arduino, HSP」も添えて。「C++」は、学校で勉強中(本記事投稿時)。触りだけなら、加えて「Java, Fortran, Ruby, Perl, Python」。最も付き合ったのはHTML周辺。GitHub.io でも Web ページ作成予定。ちなみに、今の所 GUI を構成する術は HTML & JavaScript のみ。そのうち OpenGL とかもやってみたい。
- ブログの執筆は初だが、好きに文を書くのは結構好み。ただ手書き耐性が低く、手書き原稿用紙を前にするとモチベガタ落ち。手書きレポートを要求されることがほとんど無い学科に入れて、心底嬉しく思っている。
･･･究極雑ななぐり書き説明ですが、aKuad とはこのような人物です。
さて、この記事ですが、自分流の文書作成について説明してみようかと思います。
「プログラミング関係のブログで、なぜ文書の話？」
『いえ、プログラミング関係 'だからこそ' 、文書の話です。』
私aKuadの経験を基に、「こうすると良さげなんじゃ？」と思った文書の書き方を説明致します。
ワープロでの文書作成に限った話ではありません。プレーンテキストファイルへの簡易メモでも、Webデザインでも活用できると思います。
情報系エンジニアと文書の付き合い
エンジニア、特に情報系は、何かと文書との付き合いが多い、というより、文書との付き合いは避けては通れないハズ。
例えば、あなたが何か新しいライブラリを導入するとなったとき、何かサーバソフトを導入するとなったとき･･･。
検索をかけて、いろいろな解説サイトを見て回って、見様見真似で実装したり、比べてみたり、そして出てきたエラーや不具合を検索し･･･。
あらゆるページ、すなわち文書にお世話になることと思います。今まさに Qiita をご覧になっているそこのあなたも。
そして、文書というのは、誰かが書いたから存在するもの。雑草じゃあるまいし、自生するものではありません。
自分で文書をまとめる機会も、きっと少なからず。誰かへの説明としてかもしれないし、自分への備忘録としてかもしれない文書を。
「せっかく文書を書くなら、見やすく書きたい！」
そう思われた方の、少しの参考にでもなれれば幸いです。
記事に進む前に･･･
ここに記載するのは、あくまでもaKuad流です。
「こうすると良い。」と断言するような言い方をしますが、科学的・論理的な証拠も何も用意していません。ほぼ全て僕のフィーリングです。
個人の感じ方によっては、何一つ使い物にならない書き方かもしれません。
なので、あくまでも「へぇ〜、こんな考えもあるんだなぁ〜。」程度に見て頂けると幸いです。
では、ようやく本題へ･･･。
其の一 - '目的' と '対象' をハッキリすべし
日記のようにフリーダムに綴るものはちょっと例外だが、大抵の文書に関係。
文書は特定の目的を持って書かれるはずです。ハッキリしたことを書くはずの文書が、行き先不明では意味を成しません。
文書の初めに、指針を読者に示す「この文書は、誰のための何なのか。何から何までをまとめたものなのか。」を書きましょう。
タイトルの十数文字程度だけで目的を説明できるほどシンプルな内容だとしても、物事には導入がつきものです。
タイトル: Apache のインストールをするだけ
Windows, Mac, Linux における、Apache のインストール手順です。
Apache の細かい設定についてはこの記事には書いていないので、別途 http...XXX... を参照
基礎的な事項を踏まえての、より応用的な話である場合、前提としている技術レベルなんかを書けば、対象がハッキリするでしょう。
タイトル: 自作関数に配列を渡す方法
C言語のポインタが分かり、扱えることと、自作関数が作れることを前提に話を進めます。
ポインタについては http...XXX...
自作関数については http...YYY... を参照。
ちょっとした体験談や備忘録なんかを書くときは、その文書を書いた背景を記録すべきでしょう。そのときの状況や環境なんかも忘れずに。
もしかすると、同じ状況にある人が記事を見て解決できるかも･･･！
samba の設定でちょっと詰まってしまったのでメモ･･･。
簡易的なLANで、5人程度でファイル共有をしようとしたが、
クライアントからファイルの書き込みができるようにするために、ちょっと試行錯誤した話。
サーバマシンのOS: ･･･
クライアントマシンのOS: ･･･
其のニ - '記号' と 'スペース' を活用すべし
技術関係の記事でも、案内ポスターでも、レポートでも、大抵の文書に関係。
記号を使う身近な例としては、箇条書きがあります。
口頭での説明とは違い、文字だと記号が使えます。活用しない手はありません。
例えば以下の文。口で話す、そのままの字幕のような文。見づらく、見栄えも良くありません。
マシンのCPUはRyzen7 3700X、メモリはDDR4 8GiBを二枚、グラボはRADEON RX 590、OSはUbuntu18.04です。
「変数名と数値」のような形も、またいい感じ。
上記の文を、コロンとスペースを用いてまとめてみると･･･
マシンの構成は以下の通り。
CPU: Ryzen7 3700X
メモリ: DDR4 8GiB × 2
グラボ: RADEON RX 590
OS: Ubuntu18.04
ワープロソフトやWebページであれば、表を使ってまとめるのもヨシ。
また、プログラムで言うインデントは、文書でも有効。
一つの文書の内容において、何から何まで左端から文が始まっていてはなんだかパッとしません。
個人的には、箇条書きの左部分とかにインデントを入れるのも良きかと。
それから、目立たせたい、あるいは目立たせるべき単語があれば、記号を使って装飾するのも一手。
ワープロソフトであれば、下線、太字、色の変更なんかを用いることでも可能。
プレーンテキストのように、フォント書式が設定できない状況では、記号での装飾は有効。例えば、ここの見出しのように。
其の三 - 空き行や行間等、余白を作るべし
ワープロソフトやWebデザインなら、行間は確認必須。
プレーンテキストでは、空き行でカバー。
今まさにご覧になっている Qiita の表示に注目してみると？
通常サイズの文と文の間は、およそ一文字分くらいも開いている。見出しの上は、見出しの文字一つ半が入るほどに開いているのがお分かり頂けるかと思います。
行間、重要です。僕の経験的には、行間も空き行も無しがずっと続いていると、読んでいてすさまじくストレスを感じます。
ものすごく極端な例を上げれば、「ソースコードからインデントと改行を全部抜くと修羅」って所でしょうか。
ワープロソフトとかにおいては、デフォルトでも大体適当に行間が設けられているかと思います。
何か、今手元に適当な編集可能な文書(docx とか odt とか)があれば、行間を無し(行の高さを一文字ピッタシ)にしてみてください。
行間が文書の見栄えに大きく関わっていることに気づけることと思います。
また、文のある程度の区切りごとに段落を設けるように、ちょくちょく空き行を作ると良いでしょう。この記事のような感じに。
ワープロソフトでならマージンの設定で充分ですが、プレーンテキストなら空き行必須です。
空き行、段落が無く、デカいブロックのような文字の塊では、読む気が失せます。少なくとも僕は。
其の四 - 内容を適度に区切り、構造化すべし
気楽に綴る短い日記等はちょっと例外だが、ある程度のスケールの文書に関係。
ある程度のスケールがあるのであれば、見出し分けは必須。
必要なところだけもう一度読むとなったときなんかには、どこから読むべきかをすぐに見つけられます。
スケールが非常に膨大、あるいはちょうど良く区切りれるのであれば、複数の文書に分割しても良いかもしれません。
(何かの仕様書だとか、分割すると不都合な場合は除きます。)
例えば、「Apache に関して、インストールのことと設定のこととで、別の記事に分割」というように。
ひとまず、単一の文書が肥満化するのは避けるべきでしょう。
其の五 - 最低限、同一文書内では '書式を統一' すべし
全文書における話。
記号、空白、見出しを整理したとしても、部分によって書式がバラバラでは、逆効果です。
一つの箇条書き内の同レベルの項目において、項目ごとに別々の記号を使うだなんて、ポスターの飾り付けとかじゃなければ、普通しませんよね？
(複数レベルにまたいでいるならまだしも･･･)
* Debian
- Ubuntu
+ LinuxMint
第一見出しを「行の高さ 2文字、フォントサイズ 20px、ゴシック体、太字」としたら、全ての第一見出しはこの書式で統一。
ワープロソフトであれば、「スタイル」機能を用いることで、見出しの書式なんかを統一。
プレーンテキストで、記号を用いて見出しを目立たせているなら、見出しごとに記号を統一。
---[序章]---
このテキストファイルでは...
---[其の一 - '目的' と '対象' をハッキリすべし]---
文書は特定の目的を持って･･･
単語の強調に用いる記号を、例えば「""(ダブルクォート)」と決めたなら、全ての単語強調をこれで統一。
一部例外や別記号を導入するなら、そのルールを自分で決め、統一。
表記ゆれも無くすべきでしょう。例えば、所々「ワープロソフト」だったり「ワープロ」だったりでは、文書の統一感が失われてしまいます。
略称で書くのか、略称ではなくフルで書くのかも同様です。
(口で喋るものではなく、ある程度考えて書く文なので、難しくはないはず。)
言葉を略称で表記するのであれば、最初だけ略さず書き、以降略称を用いる断りを。
もしくは、「JDK とは、Java Development Kit のことで･･･。」
この記事では、Linux への「Java Development Kit」(以下「JDK」)のインストールについて説明します。
ただ、略称の表記の方が完全に馴染みきって、略称でない表記の方が有名じゃなかったりするようであれば、わざわざ断らなくとも差し支え無いかと。
(例えば、「Slack」->「Searchable Log of All Conversation and Knowledge」)
其の六 - 自分流を作り上げるべし
記事を読んで、ちょっと思い当たる節があったそこのあなたへ。
文書の書き方は、当然一つ限りではありません。各個人によって書きやすい、書きにくいは異なります。
自分のパフォーマンスをしっかりと発揮できる書き方を、自分なりに模索しましょう。
上達するには、何事も経験の積み重ねです。
おしまいに
･･･以上、aKuad流の文書作成の心得でした。
もし、内容が気に入らなければ、この記事の存在を忘却して頂いても結構です。
結局の所、文書の書き方は十人十色ですので･･･。