開發免費和開放軟件的良好實踐:文檔

文檔:開發免費和開放軟件的良好實踐

文檔:開發免費和開放軟件的良好實踐

La 文件 是並且應該是 創作過程和計劃 所有人類活動,尤其是在技術領域,尤其是在 軟件開發.

El 所有文件的目的 一定是他 教第三方(用戶,管理員,維護者或其他開發人員),他們通常不熟悉 產品(代碼,應用程序或系統),它是如何創建的 它的結構,它的運作 甚至可能的話,說明其創建的原因及其設計和操作方式。

良好做法:文檔-簡介

此外,在特定情況下 免費軟件文檔至關重要,因為它可以完全保證 知識轉移與授權 圓滿實現的必要條件 4種自由 由它推動,它們是:

  • 0: 出於任何目的自由運行程序的自由。
  • 1: 可以自由訪問和研究程序,並為自己的利益進行更改或改編。
  • 2: 共享或重新分發副本以自由傳播和/或幫助他人的自由。
  • 3: 將修改版本的副本分發給第三方的自由。

因此,好的文檔可以使創建的產品:

  • 正確使用它,更容易教授和學習。
  • 希望對其進行修改以改進或調整它的人應完全理解。
  • 在所有潛在的相識者和陌生人之間更加自信地共享和接受。
  • 在公眾中有更好的群眾。

良好做法:文檔-自述文件

良好做法:文檔

基礎知識

在的情況下,中 自由軟件和開源開發通常 本文檔的主要用戶 與產品設計相關的是 負責維護 一樣的。 沒有好的或沒有的文檔,唯一可行的選擇是直接探索它,以實現 了解其設計和功能.

當涉及到時,沒有創建好的文檔 開發免費軟件,開源 或任何其他類型的軟件,將其發送給可能的收件人 (用戶,管理員,維護人員或其他開發人員) 在沒有地圖或指南針的叢林中找到一條出路。

為每個創建好的文檔 免費軟件,開源 這也是有益的,因為儘管 記錄有成本如果做得正確,這項投資是值得的。 因為,世界 軟體 充滿了有關的故事 遺留代碼 很少有人敢接觸的舊的或最新的程序,應用程序或系統,因為幾乎沒人能理解。 程序員專注於創建代碼,而不是正確和完整地記錄它。 這必須予以糾正。

README文本文件中文檔的良好做法

在的情況下,中 自由軟件和開源,文檔通常是由個人或一小群程序員或社區創建的文本文件。 但是,直到使用簡單的文檔創建簡單的文檔 文本文件README.md(或.txt) 你可以有你的 最佳或良好做法,提示或有用的創建指南,以向第三方提供有關已創建內容的最完整和最詳細的信息。

對於我們的文章,我們採用了 良好做法 由...構思和披露 發展守則倡議 德爾 美洲開發銀行,總而言之,它告訴我們,基於 文本文件README.md(或.txt) 它的結構必須如下:

推薦的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.

或直接訪問我們的主頁,網址為 來自Linux 或加入官方頻道 DesdeLinux的電報 閱讀此書或其他有趣的出版物並為其投票 «Software Libre», «Código Abierto», «GNU/Linux» 和其他相關主題 «Informática y la Computación»,和 «Actualidad tecnológica».


本文內容遵循我們的原則 編輯倫理。 要報告錯誤,請單擊 這裡.

成為第一個發表評論

發表您的評論

您的電子郵件地址將不會被發表。 必填字段標有 *

*

*

  1. 負責數據:MiguelÁngelGatón
  2. 數據用途:控制垃圾郵件,註釋管理。
  3. 合法性:您的同意
  4. 數據通訊:除非有法律義務,否則不會將數據傳達給第三方。
  5. 數據存儲:Occentus Networks(EU)託管的數據庫
  6. 權利:您可以隨時限制,恢復和刪除您的信息。