まず最初に私を読んでください

チームで仕事をしていると、「このツールってどんなふうに使うんやったかな」ということがあります。
また、フレームワークやライブラリを使う際にも、基本的な使い方については何かしらのドキュメントを読みながら…というやり方が主流だと思います。

README、書いてますか?

私は最近まであまり気にしていなかったのですが、仕事でもプライベートでも使う機会が増えてきたので、改めて上記について書きます。

いわゆる「まずはこれ読んでな!」というやつです。
フリーソフトをダウンロード・インストールした際によく一緒にいるアレですね。
そういった手順やノウハウをまとめたものは、ソースを公開する場合や大人数・会社間で仕事する際には必要ですよね。
かといってExcelやWordをつかって大々的にまとめるほどのものでもないという場合に、READMEの出番というわけです。

私は、Markdownを使って書くことが多いです。
まあ、簡単なHTMLみたいなもので、視覚的に書けるのでエンジニアでなくても使えます。
GithubやBitbucketのリポジトリでは「README.md」があるとそのディレクトリやページでは視覚的に表示してくれます。

# 見出し

[URL](https://k2ss.info) 

## 見出し2

- 1つめ
- 2つめ
- 3つめ

### 見出し3

1. 順序1
2. 順序2

上記のように書くと、Markdownを変換できるツールやサービスでは以下のように表示されます。

見出し

URL

見出し2

  • 1つめ
  • 2つめ
  • 3つめ

見出し3

  1. 順序1
  2. 順序2

ちょっとしたドキュメントを書くのにはピッタリですし、一緒にソース管理できるので便利ですね。
私も最近、自分が開発しているサービスにかたっぱしから導入しています(笑)。
開発環境構築時はいろんなやり方を模索しながら進めるので、「あれ、どうやってこれつくったっけ?」ということがままあります。
そんなときでも、これを読む・書くことで改めて整理できるので個人的にはとても良いなと思っています。

今回のMarkdownのように、最近は簡単にHTMLを作成できるツールも増えてきました(最近、個人的にはEmmetに興味があります)。
Excel方眼紙やテキストファイルを駆使している人(プロジェクト)は、この機会に是非抜け出しましょう!!

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA