無料でオープンなソフトウェアを開発するためのグッドプラクティス：ドキュメント

La ドキュメンテーション の基本的な部分であり、そうあるべきです 創造的なプロセスと計画 すべての人間の活動の、そして技術分野、特に ソフトウェア開発.

El すべての文書の目的 それは彼でなければなりません サードパーティ（ユーザー、管理者、メンテナー、またはその他の開発者）に教える、通常はよく知らない人 製品（コード、アプリケーション、またはシステム）、どのように作成されますか その構造、その操作 そして、可能であれば、その作成の理由とその設計と操作の方法。

さらに、の特定のケースでは 無料のソフトウェアドキュメントは不可欠です、それは完全に保証することができるので 知識の伝達とエンパワーメント の満足のいく達成のために必要 4つの自由 それによって促進されます：

• 0: 目的を問わず、好きなようにプログラムを実行する自由。
• 1: プログラムにアクセスして学習し、自分の利益のためにプログラムを変更または適応する自由。
• 2: コピーを共有または再配布して、同じものを広めたり、他の人を助けたりする自由。
• 3: 変更したバージョンのコピーをサードパーティに配布する自由。

したがって、優れたドキュメントにより、作成された製品は次のようになります。

• それは正しく使用され、より簡単に教えられ、学ぶことができます。
• それを改善または適応させるためにそれを修正したい人には完全に理解されてください。
• すべての潜在的な知人や見知らぬ人の間で、より自信を持って共有され、受け取られます。
• 国民の間でより良いミサを持っています。

グッドプラクティス：ドキュメント

基礎

の場合 フリーソフトウェアとオープンソースの開発、一般的に、 ドキュメントの主なユーザー 製品設計に関連して、現在または将来の製品は、 メンテナンスを担当 同じの。 そして、良いドキュメントがないか、ドキュメントがない場合、唯一の実行可能な代替手段は、それを直接調査して達成することです。 そのデザインと機能を理解する.

それに関しては良いドキュメントを作成していません 無料のソフトウェア、オープンソースを開発する または他の種類のソフトウェアは、その可能な受信者に送信することです （ユーザー、管理者、メンテナ、またはその他の開発者） 地図やコンパスなしでジャングルを通り抜ける方法を見つけるために。

それぞれに適したドキュメントを作成する 無料ソフトウェア、オープンソース それはまた有益ですが 文書化にはコストがかかります正しく行われた場合、投資はそれだけの価値があります。 なぜなら、 ソフトウェア についての話でいっぱいです レガシーコード 古いまたは現在のプログラム、アプリケーション、またはシステム。ほとんど誰も理解していないため、あえて触れる人はほとんどいません。 プログラマーはコードの作成に焦点を合わせ、コードを正しく完全に文書化するのではありません。 そして、これは改善されなければなりません。

READMEテキストファイルのドキュメントに関するグッドプラクティス

の場合 フリーソフトウェアとオープンソース、ドキュメントは、個人またはプログラマーやコミュニティの小グループによって作成された場合、テキストファイルに制限されることがよくあります。 しかし、単純なを使用して単純なドキュメントを作成するまで テキストファイルREADME.md（または.txt） あなたはあなたを持つことができます ベストプラクティスまたはグッドプラクティス、作成されたものについて必要な最も完全で詳細な情報をサードパーティに提供するための作成のヒントまたは便利なガイド。

私たちの記事では、 グッドプラクティス によって考案され、開示された 「開発イニシアチブのコード　 インクルード 米州開発銀行、要約すると、に基づいた優れたドキュメントは テキストファイルREADME.md（または.txt） 次のように構成する必要があります。

推奨されるREADMEファイル構造

• 説明とコンテキスト： 機能、開発されたコンテキスト、および解決に役立った開発の問題について説明する必要があるセクション。
• ユーザーガイド： デジタルツールの使用を開始する方法に関するエンドユーザーへの指示が記載されているセクション。
• インストールガイド： デジタルツールを再利用および構成するためのインストール手順について説明する必要があるセクション。 このセクションは開発者を対象としています。
• 著者 ツールの共同編集者にクレジットを付与する必要があるセクション。
• ツールコードのライセンス： デジタルツールを再利用するためにサードパーティに付与される権限を指定する必要があるセクション。
• ツールドキュメントのライセンス： 作成されたドキュメントに含まれているライセンスの種類を記載する必要があるセクション。

これらの中で 優れた実践、彼らはまたに追加することをお勧めします READMEファイルのドキュメント より完全にするために、次のセクション：

• 貢献する方法： プロジェクトに貢献するプロセスを新しい開発者に説明するセクション。
• 行動規範： 行動規範を説明するセクションでは、個人や組織がデジタルツールやそのコミュニティと何らかの形でやり取りするときに従わなければならない社会規範、規則、責任を確立します。
• バッジ： ツールの状態を読みやすく簡潔に指定するバッジ（README.mdに埋め込まれた小さな画像）を示すセクション。
• バージョン： デジタルツールのバージョンと各バージョンに追加された機能のリストを示すセクション。
• 謝辞： プロジェクトに何らかの形で貢献した他の人々または組織への謝辞を含むセクション。

この情報を拡張するには、 グッドプラクティス の問題で ドキュメンテーション の開発のため フリーソフト、によって 「開発イニシアチブのコード　 インクルード 米州開発銀行 次のリンクをクリックできます。 ドキュメント-デジタルツールを公開するためのガイド。 そして、他の出版物では、参照している部分を探求します 優れた実践 上の 評価とライセンス インクルード 無料でオープンなソフトウェア 自分自身。

結論

私たちはそれを願っています ESTA 「便利な小さな投稿　 について «Buenas prácticas» の分野で «documentación» 開発時に作成する «Software libre y abierto»、全体として、非常に興味深く、有用である «Comunidad de Software Libre y Código Abierto» そして、アプリケーションの素晴らしい、巨大で成長しているエコシステムの普及に大きく貢献しています «GNU/Linux».

そして、詳細については、いつでも訪問することを躊躇しないでください オンラインライブラリ として OpenLibra y ジェディット 読む 書籍（PDF） このトピックまたは他の人について 知識分野。 今のところ、これが好きなら «publicación», それを共有するのをやめないでください 他の人と、あなたの中で お気に入りのウェブサイト、チャンネル、グループ、またはコミュニティ ソーシャルネットワークの、できれば無料でオープンな マストドン、または安全でプライベートのように Telegram.

または、次のホームページにアクセスしてください。 DesdeLinux または公式チャンネルに参加する の電報 DesdeLinux この出版物または他の興味深い出版物を読んで投票する «Software Libre», «Código Abierto», «GNU/Linux» およびに関連するその他のトピック «Informática y la Computación»、そして、 «Actualidad tecnológica».