Передовой опыт разработки бесплатного и открытого программного обеспечения: документация

La документация является и должен быть фундаментальной частью творческий процесс и планирование всей человеческой деятельности и многое другое в технологической сфере, особенно в области Разработка программного обеспечения.

El цель всей документации это должно быть Он обучать третьих лиц (пользователей, администраторов, сопровождающих или других разработчиков), которые обычно не знакомы с продукт (код, приложение или система), как это создается его структура, его работа и даже, если возможно, причина его создания и способ его создания и эксплуатации.

Кроме того, в конкретном случае Документация по свободному программному обеспечению жизненно важна, поскольку позволяет полностью гарантировать передача знаний и расширение прав и возможностей необходимо для удовлетворительного соблюдения 4 свободы продвигаемые им, а именно:

• 0: Свобода запускать программу, как вы хотите, для любых целей.
• 1: Свобода получить доступ к программе и изучить ее, а также изменить или адаптировать ее для своей выгоды.
• 2: Свобода делиться или распространять копии, чтобы распространять то же самое и / или помогать другим.
• 3: Свобода распространять копии ваших измененных версий третьим лицам.

Таким образом, хорошая документация позволяет создать продукт:

• Его используют правильно, его легче научить и выучить.
• Будьте полностью поняты теми, кто хочет изменить его, улучшить или адаптировать.
• Делиться и принять с большей уверенностью среди всех потенциальных знакомых и незнакомцев.
• Получите лучшую массу среди публики.

Передовой опыт: документация

устои

В случае Разработка свободного программного обеспечения и открытого исходного кода, в общем-то, основные пользователи документации относительно дизайна продукта, являются или будут отвечает за техническое обслуживание того же самого. И без хорошей документации или без нее единственная жизнеспособная альтернатива - это непосредственно изучить ее, чтобы достичь понять его дизайн и функции.

Не создавать хорошую документацию, когда дело доходит до разрабатывать бесплатное программное обеспечение с открытым исходным кодом или любого другого программного обеспечения, заключается в отправке его возможным получателям (пользователи, администраторы, сопровождающие или другие разработчики) найти путь через джунгли без карты и компаса.

Создайте хорошую документацию для каждого Бесплатное программное обеспечение, открытый исходный код это также полезно, поскольку, хотя документирование имеет стоимостьВложение, если все сделано правильно, того стоит. Потому что мир Software полон историй о устаревшие коды старые или текущие программы, приложения или системы, к которым мало кто осмеливается трогать, потому что почти никто не понимает. Программисты сосредотачиваются на создании кода, а не на его правильной и полной документации. И это надо исправить.

Рекомендации по документации в текстовых файлах README

В случае Бесплатное программное обеспечение и открытый исходный коддокументация часто ограничивается текстовыми файлами, когда она создается отдельными людьми или небольшими группами программистов или сообществами. Но до создания простой документации с помощью простого текстовый файл README.md (или .txt) ты можешь иметь свой лучшие или передовые практики, советы или полезное руководство по созданию, чтобы предоставить третьим лицам наиболее полную и подробную информацию о том, что было создано.

Для нашей статьи мы взяли Best Practices задумано и раскрыто Кодекс инициативы развития из Межамериканский банк развития, что в итоге говорит нам о том, что хорошая документация, основанная на текстовый файл README.md (или .txt) Он должен иметь следующую структуру:

Рекомендуемая файловая структура README

• Описание и контекст: Раздел, в котором вы должны описать функции, контекст, в котором он был разработан, и проблемы разработки, которые он помог решить.
• Руководство пользователя: Раздел, в котором следует упомянуть инструкции для конечного пользователя о том, как начать использовать цифровой инструмент.
• Инструкция по установке: Раздел, в котором следует упомянуть инструкции по установке для повторного использования и настройки цифрового инструмента. Этот раздел предназначен для разработчиков.
• авторов Раздел, в котором должны быть предоставлены кредиты соавторам инструмента.
• Лицензия на код инструмента: Раздел, в котором необходимо указать разрешения, предоставленные третьим лицам для повторного использования цифрового инструмента.
• Лицензия на документацию инструмента: Раздел, в котором необходимо указать тип лицензии, содержащейся в создаваемой документации.

В этих хорошая практика, они также рекомендуют добавить в Документация файла README чтобы сделать его более полным, следующие разделы:

• Как внести свой вклад: Раздел, который объясняет новым разработчикам процесс участия в проектах.
• Нормы поведения: Раздел, объясняющий кодекс поведения, устанавливает социальные нормы, правила и обязанности, которым должны следовать отдельные лица и организации при любом взаимодействии с цифровым инструментом или их сообществом.
• Значки: Раздел, показывающий значки (небольшие изображения, встроенные в README.md), которые в удобочитаемой и краткой форме определяют состояние инструмента.
• Версия: Раздел, в котором указан список версий цифрового инструмента и функций, добавленных к каждой версии.
• Благодарности: Раздел, содержащий благодарности другим людям или организациям, которые так или иначе внесли свой вклад в проект.

Чтобы расширить эту информацию, на Best Practices в вопросах документация для развития Свободное программное обеспечение, посредством Кодекс инициативы развития из Межамериканский банк развития вы можете перейти по следующей ссылке: Документация - Руководство по публикации цифровых инструментов. А в других публикациях мы рассмотрим часть, относящуюся к хорошая практика на оценка и лицензирование из Бесплатное и открытое программное обеспечение самих себя.

Заключение

Мы надеемся на это это полезный небольшой пост на «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 или присоединяйтесь к официальному каналу Telegram от DesdeLinux читать и голосовать за ту или иную интересную публикацию на «Software Libre», «Código Abierto», «GNU/Linux» и другие темы, связанные с «Informática y la Computación»И «Actualidad tecnológica».