Các phương pháp hay để phát triển Phần mềm mở và miễn phí: Tài liệu

La tài liệu là và nên là một phần cơ bản của quá trình sáng tạo và lập kế hoạch của tất cả hoạt động của con người và hơn thế nữa trong lĩnh vực công nghệ, đặc biệt là trong lĩnh vực Phát triển phần mềm.

El mục đích của tất cả các tài liệu đó phải là Ngài dạy bên thứ ba (người dùng, quản trị viên, người bảo trì hoặc các nhà phát triển khác), những người thường không quen thuộc với sản phẩm (mã, ứng dụng hoặc hệ thống), nó được tạo ra như thế nào cấu trúc của nó, hoạt động của nó và thậm chí nếu có thể, lý do tạo ra nó và cách thức thiết kế và hoạt động của nó.

Hơn nữa, trong trường hợp cụ thể của Tài liệu về Phần mềm Miễn phí rất quan trọng, vì nó cho phép hoàn toàn đảm bảo chuyển giao kiến ​​thức và trao quyền cần thiết để thực hiện thỏa đáng 4 quyền tự do được quảng cáo bởi nó, đó là:

• 0: Tự do chạy chương trình như mong muốn, cho bất kỳ mục đích nào.
• 1: Quyền tự do truy cập và nghiên cứu một chương trình, và thay đổi hoặc điều chỉnh nó vì lợi ích của riêng bạn.
• 2: Quyền tự do chia sẻ hoặc phân phối lại các bản sao để truyền bá bản sao giống nhau và / hoặc giúp đỡ người khác.
• 3: Quyền tự do phân phối các bản sao của các phiên bản đã sửa đổi của bạn cho các bên thứ ba.

Do đó, một tài liệu tốt giúp sản phẩm được tạo ra có thể:

• Nó được sử dụng một cách chính xác, và nó dễ dàng được dạy và học hơn.
• Được hiểu thấu đáo bởi những người muốn sửa đổi nó để cải thiện hoặc thích ứng nó.
• Được chia sẻ và đón nhận với sự tự tin hơn, giữa tất cả những người quen và người lạ tiềm năng.
• Có một số đông tốt hơn trong số công chúng.

Thực hành tốt: Tài liệu

Nguyên tắc cơ bản

Trong trường hợp của Phát triển phần mềm miễn phí và mã nguồn mở, nói chung là, người dùng chính của tài liệu liên quan đến thiết kế sản phẩm, là những sản phẩm đang hoặc sẽ chịu trách nhiệm bảo trì của cùng một. Và nếu không có tài liệu tốt hoặc không có tài liệu, giải pháp thay thế khả thi duy nhất là trực tiếp khám phá nó, để đạt được hiểu thiết kế và chức năng của nó.

Không tạo tài liệu tốt khi nói đến phát triển phần mềm miễn phí, mã nguồn mở hoặc bất kỳ loại phần mềm nào khác, là để gửi cho người nhận (người dùng, quản trị viên, người bảo trì hoặc nhà phát triển khác) để tìm đường xuyên qua khu rừng rậm mà không cần bản đồ hoặc la bàn.

Tạo tài liệu tốt cho mỗi Phần mềm miễn phí, mã nguồn mở nó cũng có lợi, vì mặc dù lập hồ sơ có chi phíKhoản đầu tư, nếu được thực hiện đúng cách, rất xứng đáng. Bởi vì, thế giới của Phần mềm đầy những câu chuyện về mã kế thừa của các chương trình, ứng dụng hoặc hệ thống cũ hoặc hiện tại mà chỉ có rất ít người dám động đến, vì hầu như không ai hiểu. Các lập trình viên tập trung vào việc tạo mã và không ghi lại nó một cách chính xác và đầy đủ. Và điều này phải được khắc phục.

Các phương pháp hay về tài liệu trong tệp văn bản README

Trong trường hợp của Phần mềm miễn phí và nguồn mở, tài liệu thường bị hạn chế đối với các tệp văn bản, khi nó được tạo bởi các cá nhân hoặc nhóm nhỏ lập trình viên hoặc cộng đồng. Tuy nhiên, ngay cả khi tạo một tài liệu đơn giản bằng cách sử dụng tệp văn bản README.md (hoặc .txt) bạn có thể có của bạn thực hành tốt nhất hoặc tốt, thủ thuật hay hướng dẫn tạo hữu ích nhằm mang đến cho bên thứ ba thông tin chi tiết và đầy đủ nhất cần thiết về những gì đã được tạo.

Đối với bài viết của chúng tôi, chúng tôi đã sử dụng Thực hành tốt hình thành và tiết lộ bởi "Mã cho Sáng kiến ​​Phát triển" các Ngân hàng phát triển liên Mỹ, theo cách tóm tắt cho chúng ta biết rằng tài liệu tốt dựa trên tệp văn bản README.md (hoặc .txt) Nó phải được cấu trúc như sau:

Cấu trúc tệp README được đề xuất

• Mô tả và ngữ cảnh: Phần nơi các chức năng phải được mô tả, bối cảnh nơi nó được phát triển và các vấn đề phát triển mà nó đã giúp giải quyết.
• Hướng dẫn sử dụng: Phần hướng dẫn cho người dùng cuối về cách bắt đầu sử dụng công cụ kỹ thuật số nên được đề cập.
• Hướng dẫn cài đặt: Phần hướng dẫn cài đặt để sử dụng lại và cấu hình công cụ kỹ thuật số nên được đề cập. Phần này dành cho các nhà phát triển.
• tác giả Phần nơi tín dụng phải được trao cho các cộng tác viên của công cụ.
• Giấy phép cho mã công cụ: Phần nơi các quyền được cấp cho bên thứ ba để sử dụng lại công cụ kỹ thuật số phải được chỉ định.
• Giấy phép cho tài liệu của công cụ: Phần nơi loại giấy phép có trong tài liệu được tạo phải được đề cập.

Trong đó thực hành tốt, họ cũng khuyên bạn nên thêm vào Tài liệu tệp README để làm cho nó đầy đủ hơn, các phần sau:

• Cách đóng góp: Phần giải thích cho các nhà phát triển mới quy trình đóng góp cho các dự án.
• Quy tắc ứng xử: Phần giải thích quy tắc ứng xử thiết lập các chuẩn mực xã hội, quy tắc và trách nhiệm mà các cá nhân và tổ chức phải tuân theo khi tương tác theo bất kỳ cách nào với công cụ kỹ thuật số hoặc cộng đồng của họ.
• Danh hiệu: Phần hiển thị các huy hiệu (hình ảnh nhỏ được nhúng trong README.md) chỉ định trạng thái của công cụ theo cách dễ đọc và ngắn gọn.
• Phiên bản: Phần chỉ ra danh sách các phiên bản của công cụ kỹ thuật số và các chức năng được thêm vào mỗi phiên bản.
• Sự nhìn nhận: Phần chứa những lời cảm ơn tới những người hoặc tổ chức khác đã đóng góp theo một cách nào đó cho dự án.

Để mở rộng thông tin này, trên Thực hành tốt trong các vấn đề Tài liệu vì sự phát triển của Phần mềm miễn phí, bằng "Mã cho Sáng kiến ​​Phát triển" các Ngân hàng phát triển liên Mỹ bạn có thể nhấp vào liên kết sau: Tài liệu - Hướng dẫn xuất bản các công cụ kỹ thuật số. Và trong các ấn phẩm khác, chúng ta sẽ khám phá phần đề cập đến thực hành tốt trên đánh giá và cấp phép các Phần mềm miễn phí và mở chúng tôi.

Kết luận

Chúng tôi hy vọng rằng này "bài viết nhỏ hữu ích" về «Buenas prácticas» trong lĩnh vực «documentación» để tạo ra khi phát triển «Software libre y abierto», rất được quan tâm và tiện ích, cho toàn bộ «Comunidad de Software Libre y Código Abierto» và đóng góp to lớn vào việc truyền bá hệ sinh thái tuyệt vời, khổng lồ và đang phát triển của các ứng dụng và «GNU/Linux».

Và để biết thêm thông tin, đừng ngần ngại truy cập bất kỳ Thư viện trực tuyến như OpenLibra y jedit đọc sách (PDF) về chủ đề này hoặc chủ đề khác lĩnh vực kiến ​​thức. Còn bây giờ, nếu bạn thích điều này «publicación», đừng ngừng chia sẻ nó với những người khác, trong Các trang web, kênh, nhóm hoặc cộng đồng yêu thích của mạng xã hội, tốt nhất là miễn phí và mở như Loại voi lớn đa tuyệt chủnghoặc an toàn và riêng tư như Telegram.

Hoặc chỉ cần truy cập trang chủ của chúng tôi tại DesdeLinux hoặc tham gia Kênh chính thức Điện tín của DesdeLinux để đọc và bình chọn cho ấn phẩm này hoặc các ấn phẩm thú vị khác trên «Software Libre», «Código Abierto», «GNU/Linux» và các chủ đề khác liên quan đến «Informática y la Computación»và «Actualidad tecnológica».