README

cURLのREADMEファイルのスクリーンショット

README ファイルには、そのファイルがあるディレクトリの内容に関する 説明情報が含まれています。情報の範囲は通常、ディレクトリ内のファイルに限られますが、子ディレクトリやディレクトリツリー全体が含まれる場合もあります。この名前は、ディレクトリの内容に関する重要な情報や方向性を示す情報にユーザーの注意を向けるためのものです。ディレクトリの内容に詳しくない人は、まずREADMEファイルを他のファイルよりも先に読むのが賢明です。READMEという名前がよく使われますが、「Read Me」や「READ.ME」など、同じ目的で使われる類似の名前も数多くあります。ファイル名には、プレーンテキストの場合は「README.txt」、 Markdownの場合は「README.md」など、ファイル形式を示す拡張子が含まれる場合もあります。[ 1 ]ファイル名は通常すべて大文字です。

アーカイブは単一のファイルとして保存されるディレクトリのようなものなので、アーカイブ内の README ファイルはディレクトリ内のものと同じように動作します。

コンテンツ

READMEファイルの形式と内容は標準化されていないため、大きく異なります。ソフトウェアプロジェクトの場合、READMEファイルには通常、次のような情報が含まれます。

歴史

READMEファイルを添付する慣習は1970年代半ばに始まりました。[ 3 ] [ 4 ] [ 5 ] [ 6 ] [7] [ 8 ] [ 9 ] Unixでは、ほとんどのファイル名が小文字であったため、ファイル名は大文字で書かれていました。これは、ファイル名が目立つようにするためであり、 ASCII順序のリストの先頭近くに表示されるためです。初期のMacintoshシステムソフトウェアは、起動ディスクにREADMEファイルをインストールし、READMEファイルはサードパーティ製ソフトウェアに付属することが一般的でした。

特に、フリーソフトウェアやオープンソースソフトウェアにはREADMEファイルが含まれる長い歴史があり、GNUコーディング標準では「パッケージの概要」を提供するためにREADMEファイルを含めることを推奨しています。[ 10 ]

ソフトウェア配布の事実上の標準プラットフォームとしてWebが登場して以来、多くのソフトウェア パッケージは上記の補助ファイルや情報の一部をWeb サイトやwikiに移動 (またはコピー) しており、README 自体が含まれている場合もあれば、ソフトウェアの新規ユーザーが必要とするすべての情報が含まれていない短い README ファイルだけが残されている場合もあります。

人気のソースコードホスティングウェブサイトGitHubはREADMEファイルの作成を強く推奨しています。リポジトリのメイン（最上位）ディレクトリにREADMEファイルが存在する場合、リポジトリのフロントページに自動的に表示されます。[ 11 ]プレーンテキストに加えて、さまざまな他の形式とファイル拡張子もサポートされており、[ 12 ] HTML変換では拡張子が考慮されます。特にREADME.mdはGitHub Flavored Markdownとして扱われます。

ディレクトリコンテンツのメタデータは、READMEに加えて、またはREADMEの代わりにファイルに保存されることがあります。[ 13 ]次の表は、よく使用されるファイル名と、そのファイルによく含まれる内容を示しています。READMEと同様に、ファイル名やその内容を規定する正式な標準はありません。ただし、Gnits StandardsとGNU Autotoolsによって定められた規則はあります。

README 一般情報
著者 クレジット
ありがとう 謝辞
変更履歴プログラマー向けの詳細な変更ログ
ニュース ユーザー向けの基本的な変更ログ
インストール インストール手順
コピー/ライセンス 著作権とライセンス情報
バグ 既知のバグと新しいバグを報告する手順
貢献/ハッキング プロジェクトへの将来の貢献者のためのガイド
よくある質問よくある質問と回答
やるべきこと計画された変更

参照

参考文献

  1. ^レイモンド、エリック・スティーブン(1996). 『新ハッカー辞典』MITプレスpp.  378–79 . ISBN 978-0-26268092-9README は、伝統的に Unix ソース ディストリビューションの最上位ディレクトリに含まれるハッカーの視点からの序文で、より詳細なドキュメント、クレジット、さまざまな変更履歴、注記などへのポインタが含まれています。 […] ハッカーに尋ねられると、README の慣習は必ず、ルイス・キャロルの『不思議の国のアリス』でアリスが「私を食べて」と「飲んで」と書かれた魔法のお菓子と対峙する有名なシーンに関連があると答えます。
  2. ^ a bマネス、スティーブン（1996年11月）「README？買う前に必ず読んで！」PC World 14 ( 11): 366.
  3. ^ "PDP-10 アーカイブ: decus/20-0079/readme.txt from decus_20tap3_198111" . pdp-10.trailing-edge.com . 1974-11-27 . 2018-03-03取得. [README.TXT は SPICE/SINC/SLIC の DOC ファイルです] このフェイルセーフテープには、Applications Software Bulletin Volume 4 に記載されている回路解析プログラム SPICE SINC および SLIC が含まれています。要件：SPICE は右調整ホレリスデータを使用するため、FORTRAN-10 バージョン 4 が必要です。実行時間は約 47K です。[…] また、このファイル、SAV に付随する FOROTS、およびタイミングルーチン SECOND.MAC のソースも含まれています。SPICE は 1SPICE.FOR、2、3 の 3 つの部分に分かれています。各プログラムを説明する印刷されたドキュメントがあります。これらはDECUSパケットに含まれています。ドキュメントとプログラムは、もともとカリフォルニア大学バークレー校電気工学科でCDC 6400上で開発されました。FORTRANをDECsystem-10に変換する以外は、プログラムに変更はありません。テストデータでは、SLICとSINCは6400と比較して若干の差異が見られましたが、SPICEでは差異は見られませんでした。頑張ってください！ Ashley Grayson 1974年11月27日 [README.TXT終了]
  4. ^ "DECUS 10-LIB-4 10-210から10-241までを収録（10-223は除く）" . pdp-10.trailing-edge.com . 1975年3月27日. 2018年3月3日閲覧。このFAILSAFEテープ上のファイルはUCI LISPシステムを構成しています。その大部分は、カリフォルニア州アーバインにあるカリフォルニア大学情報コンピュータサイエンス学部から入手できるUCI LISPマニュアルに記載されています。[1]
  5. ^ 「Programmer's Workbench /sys/source/lex/README」 1977年7月. 2020年1月25日閲覧。
  6. ^ 「Unix 7th edition /usr/doc/README」 . 1979年. 2020年1月25日閲覧。
  7. ^ 「最初の32ビットBSD usr/doc/README」 1980年3月. 2020年1月25日閲覧。
  8. ^ Langemeier, Jeff (2011-07-29). 「Re: READMEの起源」. 2020年1月25日閲覧– Stackexchange経由。[…] パンチカードや磁気テープ、その他「プログラム」とされるほぼすべての製品にREADME（実際の印刷ファイル）が用意されていました。当時は、プログラムの作成、実行、その他すべての作業に膨大な労力がかかったため、READMEは本当に必要でした。これらのREADMEには、エラーチェックとデバッグの一環として、パンチカードのパンチ方法の実際の印刷物も含まれていました。この慣習は、パンチカードすべてにREADMEという大文字の文字が印刷された「リーム」と呼ばれる紙が添付されていたという点で、旧来のシステムに従っているようです。この紙には、パンチカードの使用方法とシステムへの読み込み方法がすべて記載されていました。参考までに、これは1960年代のことだったでしょう。[…]
  9. ^ Abdelhafith, Omar (2015年8月13日). 「README.md: History and Components」 . 2020年1月25日時点のオリジナルよりアーカイブ。 2020年1月25日閲覧。
  10. ^ 「GNUコーディング標準：リリース」www.gnu.org . 2018年3月3日閲覧。
  11. ^ 「READMEについて」 . GitHub Docs . 2024年5月31日閲覧。
  12. ^ "マークアップ" . GitHub . 2014年12月25日. 2015年2月8日閲覧。
  13. ^ Prana, Gede Artha Azriadi; Treude, Christoph; Thung, Ferdian; Atapattu, Suchhari; Lo, David (2019-06-01). 「GitHub READMEファイルのコンテンツの分類」 . Empirical Software Engineering . 24 (3): 1296– 1327. arXiv : 1802.06997 . doi : 10.1007/s10664-018-9660-3 . ISSN 1573-7616 . 

さらに読む

この記事は、パブリック ドメインのJargon Fileに一部基づいています。

「 https://en.wikipedia.org/w/index.php?title=README&oldid=1329057101」から取得