Пользовательская документация: Пользовательская документация и GitHub / Хабр

Содержание

Пользовательская документация и GitHub / Хабр

Сталкивались ли вы когда нибудь с долгим поиском документации к используемой библиотеке или пакету? Я считаю странным, что исходный код не распространяется с пользовательской документацией. Ведь она такая же важная часть кода, как тесты или зависимости. Без хорошей пользовательской документации мы можем «убить» уйму времени на анализ кода и комментариев. Так почему бы не хранить пользовательскую документацию вместе с исходными кодами программы? Речь не о DocBlock и генерацию документации по API проекта, я говорю именно о пользовательской документации, которую мы так любим за последовательное повествование и множество примеров.

В этой статье я приведу один из способов хранения пользовательской документации вместе с исходными кодами программы так, чтобы это было удобно как для разработчиков, так и для пользователей.

Многим статья может показаться «капитанской». Если вы почувствуете на своих щеках соленые брызги и услышите шум волн, немедленно прекратите чтение!

В отличии от документации, добавляемой прямо в исходные коды (в виде комментариев), пользовательская документация более «user-ориентированная», если можно так выразится. Представьте, что вы долго искали подходящую библиотеку и вдруг коллега назвал ту, которая «может вам подойти». Вы быстро находите ее на GitHub, но с чего начать? Хорошо если в корне есть файл README.md, но даже ознакомление с ним может оставить множество вопросов. Обычно все заканчивается одним исчерпывающим примером (если библиотека не большая) или ссылкой на официальную документацию в виде Web-сайта или PDF документа. После доступа к одному из этих ресурсов вы вздыхаете с облегчением, внимательно читаете несколько страниц, изучаете пятерку примеров и начинаете уверенно пользоваться библиотекой.

Пользовательская документация — это лицо вашего проекта. Чем она доступнее, тем меньше пользователей бросят идею изучения вашего решения из-за проблемы новизны.

Использование Web-сайта или документа в качестве пользовательской документации это хорошее решение, но у него есть несколько минусов:

Документация отделена от проекта и, возможно, пользователю будет сложно получить к ней доступ

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

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

Документация может стать недоступной по техническим причинам (упал Web-сайт, потерялась ссылка на документ т.д.)Потому сейчас я постараюсь убедить вас в пользе хранения пользовательской документации прямо внутри проекта.

Вы храните unit-тесты вашего проекта вместе с кодом или в отдельном репозитории? Обычно они находятся в каталоге tests и являются неотъемлемой частью проекта. С документацией так же. Она — часть вашего проекта, но в отличии от тестов, она нужна пользователям не для проверки работоспособности вашего решения, а для быстрого и безболезненного ознакомления с ним.

Я предлагаю выделить для пользовательской документации отдельный каталог в вашем проекте. Пусть он называется docs и содержит файлы с расширением md (почему выбран именно Markdown вы узнаете позже). Полезно так же снабдить вашу пользовательскую документацию «точкой входа» — это файл оглавления, с помощью которого пользователям будет проще ориентироваться в этом каталоге. Я предпочитаю называть этот файл index.md и записывать в него список ссылок на остальные файлы в этом каталоге.

Пример

1. [Введение](./getting-started.md)
2. [Обработка файлов](./files.md)
3. [Работа в сети](./network.md)

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

В пользовательской документации должна быть «точка входа» — документ, который ознакомит читателя со структурой и содержанием.

Остальные файлы должны содержать подробное описание компонентов вашего решения, подробные примеры использования и возможные проблемы, с которыми может столкнуться пользователь. Лучше, чтобы эти файлы не были связаны друг с другом, чтобы пользователь мог начать изучение того компонента, который он считает нужным.
После того, как пользовательская документация будет готова, добавьте в корень вашего проекта файл README.md, в котором будет ссылка на «точку входа» вашей документации.Пример

# Bricks.Cli.Routing

Пакет позволяет работать с данными, получаемыми при вызове PHP интерпретатора из 
командной строки. Он так же реализует маршрутизацию на основе опций вызовов 
командной строки.

## Установка и Автозагрузка

Этот пакет сопровождается файлом [composer.json][], что позволяет использовать 
[Composer][] для его инсталляции и автозагрузки.

Так же можно установить его загрузив [исходные коды][] пакета в виде Zip архива 
или клонировав этот репозиторий. Все компоненты этого пакета загружают 
зависимости автоматически.

Перед использованием рекомендуется выполнить тестирование с помощью утилиты 
[PHPUnit][] вызвав ее в корневом каталоге пакета.

## Зависимости

Этот пакет зависит от интерпретатора PHP версии 5.5 или выше.

## Поддержка

Если у вас возникли сложности или вопросы по использованию пакета, создайте 
[обсуждение][] в данном репозитории или напишите на электронную почту 
<[email protected]>.

## Документация

Пользовательскую документацию можно получить по [ссылке](./docs/index.md).

Документацию API можно получить из исходных кодов пакета или с помощью утилиты 
[Doxygen][].

[composer.json]: ./composer.json
[Composer]: http://getcomposer.org/
[исходные коды]: https://github.com/Bashka/bricks_cli_routing/releases
[PHPUnit]: http://phpunit.de/
[обсуждение]: https://github.com/Bashka/bricks_cli_routing/issues
[Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html

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

Так как вся документация находится в репозитории, на нее удобно ссылаться извне по ссылке вида: https://raw.githubusercontent.com/Bashka/bricks_cli_routing/master/docs/call.md — а если «прикрутить» сюда Web-интерфейс, то можно получить полноценный Web-сайт без необходимости переноса документации. Удобно не правда ли?

Более того, если вы переместите документацию из каталога docs в каталог docs/ru, то позволите вашим пользователям переводить ее просто добавляя новые каталоги и копируя в них переведенные файлы документации.

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

Документация программного обеспечения

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

Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате.

Программный документ — документ, содержащий в зависимости от назначения данные, необходимые для разработки, производства, эксплуатации, сопровождения программы или программного средства.

Типы документации

Существует четыре основных типа документации на ПО:

архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО

техническая — документация на код, алгоритмы, интерфейсы, API

пользовательская — руководства для конечных пользователей,

администраторов системы и другого персонала

маркетинговая

Архитектурная/проектная документация

Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так». Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи, как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.

Техническая документация

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

Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.

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

Пользовательская документация

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

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

инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение. Существует три подхода к организации пользовательской документации. Вводное руководство (англ. tutorial), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.

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

Маркетинговая документация

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

подогреть интерес к продукту у потенциальных пользователей

информировать их о том, что именно делает продукт, с тем, чтобы их ожидания совпадали с тем, что они получат

объяснить положение продукта по сравнению с конкурирующими решениями

Одна из хороших маркетинговых практик — предоставление слогана, простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт.

Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.

Документирование в разработке ПО / Хабр

INTRO

Добрый день, уважаемое сообщество.
Позвольте представиться. Я бизнес-аналитик, уже десять лет работаю в области разработки заказного программного обеспечения, в последнее время совмещаю роли аналитика и руководителя проектов.

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

Поэтому на всех своих проектах я стараюсь изначально построить процесс так, чтобы неопознанного и неописанного функционала не было, все члены команды вовремя получали актуальную информацию и вообще был мир во всём

Итак, для начала отвечу на главный вопрос: для чего всё это нужно.

Есть несколько причин.

1. Документация обеспечивает «общее пространство» проекта. Любой участник в любой момент времени может получить необходимую информацию как по конкретной задаче, так и по общему направлению работы.

2. Команда говорит «на одном языке» — ведь гораздо проще понять человека, сообщающего «об ошибке в функции, описанной в Use Case №12», чем «о стрёмном баге в той фигне, которую Вася месяц назад делал».

3. Документирование позволяет четко разграничить зоны ответственности между участниками проекта.

4. Только тщательно описанные требования могут быть проверены на полноту и непротиворечивость. «Наколенные записки» — прямой и очень быстрый путь к тому, что границы проекта расползутся резвыми тараканами, а функционал, задуманный вначале, не будет монтироваться с возникающими в процессе «хотелками» заказчика.

Для себя я выработала набор базовых правил, которые позволяют эффективно документировать, планировать и контролировать разработку в комфортных для всех участников условиях.

1. Документация не должна быть избыточной и объемной. Мы пишем документы не за-ради приятного процесса постукивания по клавишам, а для того, чтобы их использовать в работе. Избыточное количество текста – раздражает и затрудняет восприятие.

2. Вся схема документирования проекта должна быть взаимоувязанной и логичной. Если в схеме существует документ, который не связан ссылкой с каким бы то ни было другим документом, то его можно безболезненно из схемы исключить.

3. Вся оценка трудозатрат должна производиться только на основании описанных атомарных задач. Сложно оценить разработку «функционала подсистемы ввода данных», гораздо проще оценить задачи «разработка формы ввода данных марсиан» и «разработка фильтра списка марсиан». Чем мельче оцениваемый элемент – тем точнее будет агрегированная оценка.

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

Я предлагаю на суд уважаемого сообщества схему документирования, которая кажется мне удобной, логичной и правильной. И – да, это работает.

Итак, какие типы документов используются в схеме.

1. Техническое задание.

2. Частное техническое задание (опционально).

3. Сценарий использования (Use Case).

4. Сценарий тестирования (Test Case).

5. Отчет об ошибке (Bug Report).

6. Руководство пользователя.

7. Руководство администратора (опционально).

На рисунке ниже — схема связи между этими документами.

Как это работает?

ТЗ

Изначально, при обследовании, формируется Большое Техническое задание.
Оно включает в себя:
• словарь терминов предметной области;
• описание предметной области;
• описание ролевой системы;
• описание функциональных требований;
• описание нефункциональных требований.
Описание требований в этом документе фиксируется на «верхнем уровне», то есть мы описываем не конкретные действия, а только необходимые функции. Требования оптимально разбивать на смысловые группы по подсистемам.
Например, мы описываем подсистему «Администрирование» с функциями «Создание карточки пользователя», «Удаление карточки пользователя», «Редактирование карточки пользователя». Это требования верхнего уровня, ниже в ТЗ опускаться смысла нет.

ЧТЗ

В случае, если система большая, разумно сделать Частные технические задания на каждую подсистему.
ЧТЗ должны содержать:
• ссылку на пункт ТЗ;
• максимально подробную информацию по каждой функции;
• список UseCases для функции.
Таким образом реализуется преемственность документов, что позволяет, во-первых, унифицировать их форму, во-вторых – частично реализовать повторное использование, то есть снизить затраты времени на «писанину».
Например, мы формируем ЧТЗ на всё ту же подсистему «Администрирование». Оно будет содержать описание функции: «Создание карточки. Необходимо реализовать следующий функционал: вызов карточки посредством кнопки «Создать», интерфейс карточки, содержащий следующий набор полей, сохранение карточки посредством кнопки «Сохранить», отмену сохранения посредством кнопки «Отмена»».

Use Case

Use Case — суть вариант использования, он описывает все действия, которые пользователь может произвести, и реакцию системы на эти действия.
Каждый Use Case должен быть привязан к пункту ЧТЗ.
Наиболее оптимальным, на мой взгляд, является формат описания, включающий в себя:
• Макет экрана. Макеты можно делать и сложные, «кликабельные», но, по опыту, хватает «проволочной диаграммы», сделанной с помощью Visio или аналогичного инструмента. Если на форме предполагается использование модальных окон, то они тоже должны быть прорисованы, нижеописанные таблицы для них должны дублироваться.
• Диаграмму действий экрана, в графическом виде описывающую алгоритм работы функции.
• Таблицу с описанием полей. В строке таблицы должны располагаться следующие данные: название поля, тип поля, ограничение на ввод данных (логические проверки и т.д.), роли пользователей, которым доступно чтение/редактирование поля. Если поле расчетное – то необходимо указывать формулу для расчета значения.
• Таблицу с описанием действия кнопок экрана. В строке таблицы должны содержаться данные о названии кнопки, описание действия при клике и путях перехода, если щелчок по кнопке предполагает переход на другой экран, роли пользователей, которым доступно действие.
Также возможно небольшое общее описание функционала но, как правило, оно просто не нужно.

Test Case

Test Case, что вполне самоочевидно, должен содержать описание тестовых сценариев.
В идеале, каждый такой документ привязывается к соответствующему Use Case, но бывает так, что логично объединить несколько Use Cases в один Test Case.
Оптимальным вариантом формата описания является таблица, содержащая в одном столбце описание атомарной операции, влекущей ответное действие системы, во втором – описание правильной реакции системы. Описывать, к примеру, процесс ввода текста в текстовое поле не нужно, а вот проверку валидности данных при сохранении (щелчке по кнопке «Сохранить») – обязательно.

Bug Report

Ещё немного побуду кэпом: Bug Report возникает в процессе тестирования системы как реакция тестировщика на ошибку. Каждый документ должен обязательно ссылаться на соответствующий Test Case.
Содержать документ должен:
• скриншот возникшей ошибки;
• описание предшествующих действий. Лучше всего разработать удобный для всех шаблон такого описания – это сильно экономит время разработчикам при воспроизведении бага;
• текстовое описание самой ошибки.

Руководство пользователя/Руководство администратора

Самые занудные в написании, но, тем не менее, жизненно необходимые документы.
По сути, их формирование можно даже автоматизировать, если все Test Cases и Use Cases были написаны с должным старанием и правильно оформлены.
Я не буду подробно на них останавливаться, если вдруг тема заинтересует – расскажу о том, как их составление можно автоматизировать.

Заключение

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

Пользовательская документация — КиберПедия

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

В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так.

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.

Существует три подхода к организации пользовательской документации. Вводное руководство (англ. tutorial), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.

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

Маркетинговая документация

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

· подогреть интерес к продукту у потенциальных пользователей

· информировать их о том, что именно делает продукт, с тем чтобы их ожидания совпадали с тем, что они получат

· объяснить положение продукта по сравнению с конкурирующими решениями

Одна из хороших маркетинговых практик — предоставление слогана — простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт.

Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.

Документация на техническое обеспечение

ОБЩИЕ ПОЛОЖЕНИЯ

1.1. Документация по техническому обеспечению АСУ предназначена для описания проектных решений по техническому обеспечению в документах:

· описание комплекса технических средств;

· структурная схема комплекса технических средств;

· план расположения;

· перечень заявок на разработку новых технических средств;

· перечень заданий заказчику АСУ (Генпроектировщику) на проектирование в смежных частях проекта объекта, связанное с созданием АСУ;

· ведомость оборудования и материалов;

· технические требования к технологическому объекту управления;

· задание на проектирование в смежной части проекта объекта, связанное с созданием АСУ;

· проектная оценка надежности комплекса технических средств;

· принципиальная схема;

· схема автоматизации;

· таблица соединений и подключений;

· схема соединений внешних проводок;

· чертеж общего вида;

· схема подключений внешних проводок;

· спецификация оборудования;

· чертеж установки технических средств;

· ведомость потребности в материалах.

(Измененная редакция, Изм. № 1)

1.2. При разработке документов на подсистему содержание разделов каждого документа ограничивают рамками данной подсистемы.

1.3. В зависимости от назначение и специфических особенностей создаваемых АСУ допускается включать в документы дополнительные разделы и сведения, требования к содержанию которых не установлены настоящим стандартом.

1.4. Отсутствие проектных решений по разделу документа фиксируют в соответствующем разделе с необходимыми пояснениями.

ТРЕБОВАНИЯ К СОДЕРЖАНИЮ ДОКУМЕНТОВ

О стандартах документации / Хабр

Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно?

Существует тьма статей на тему «как писать документацию», но если вы решили взяться за неё в первый раз, то в новой для вас области не сразу понятно, дело ли пишет автор, или отсебятину выдумывает.

Для того чтобы сформировать своё мнение без перелопачивания статей, можно пойти двумя путями: довериться некому авторитету или посмотреть в стандарты – уж там-то с наибольшей вероятностью проблему обдумали со всех сторон.

Кто-то может сказать «а-а, стандарты! они ещё более адово скучные, чем сама документация!». Ну, не будем врать, есть немного 🙂 Но если у вас документ в электронном формате – найти необходимое не составляет труда. И кроме того, ну надо же размочить раздел стандарты уже, а то висит пустой, даже обидно.

Наши.

Обратимся сначала к ГОСТ-ам. Они расстраивают датами разработки (впрочем, похоже, за эти годы в документировании не многе изменилось) и радуют бесплатностью.

ГОСТ Р ИСО 9127-94 «Документация пользователя и информация на упаковке для потребительских программных пакетов» – наиболее приглянувшийся мне стандарт из наших. Довольно кратко (весь документ – около 20 страниц) указаны основные требования к составу и содержанию документации пользователя.
Официальная страница. Скачать PDF.

ГОСТ Р ИСО/МЭК 15910-2002 «Процесс создания документации пользователя программного средства» — стандарт больше отвечает не на вопрос «Что» должно быть в документе, а «Как» должен создаваться документ. Дополнительно есть подробное описание стиля документа с примером – довольно удобная штука для создания шаблона: один раз запариваешься (и забиваешь в шаблон всё: от выравнивания до формата подписей рисунков), а потом клепаешь документы все одного вида, а не с заголовками разного шрифта.
Официальная страница. Скачать PDF.

ГОСТ-ы серии 19.хх – серия ЕСПД, страсть, какая древняя (в среднем, документы созданы в 78-м году), но зато такие же лаконичные, как в ГОСТ 9127, требования ко многим видам документов.
Ознакомиться.

ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ. Спасибо Jazzist.

Буржуйские.

Не было предела моему возмущению, когда я узнала, что международные стандарты не бесплатные. Это как правила дорожного движения сделать платными. Но в принципе, может и резонно: организации-то не государственные. Хотят – могут и деньги брать за свою работу. К счастью, многие стандарты можно скачать по-привычному, по-пиратски.

IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» — в документе обозначены требования к структуре, содержимому и формату инструкций пользователя.
Официальная страница.

IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» — рекомендации к документам, описывающим архитектуру программного обеспечения, то бишь к техническому описанию.
Официальная страница.

Особливо понравилась табличка-экстракт основного содержания документа (здесь вольный перевод):

Тип обзора	Содержание	Атрибуты	Примеры представления
Декомпозиция	Разбиение системы на структурные составляющие	Определение, тип, назначение, функции, зависимые сущности	Иерархическая диаграмма декомпозиции, словесное описание.
Описание зависимостей	Описание связей между сущностями и системными ресурсами.	Определение, тип, назначение, зависимости, ресурсы.	Структурные схемы, диаграммы потоков данных, схемы транзакций.
Описание интерфейса	Список всего, что может потребоваться знать проектировщику, программисту или тестеру для того чтобы использовать структурные составляющие системы.	Определение, функции, интерфейсы.	Файлы интерфейса, таблицы параметров.
Описание деталей	Описание внутреннего устройства частей сущности.	Определение, обработка данных, данные.	Блок-схемы, N-S диаграммы, PDL

ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» — рекомендации по созданию документации пользователя. Так сказать, советы «хозяйке на заметку». Довольно приятное руководство с большим количеством примеров (имхо, больше подходит для чтения до или в самом начале создания документации, так как подходит к процессу основательно, от самого планирования). Также в приложениях есть чеклисты «что не забыть сделать в процессе разработки документации» и «что должно быть в документе»
Официальная страница.

ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» — довольно свежий и, судя по содержанию, полезный документ. Но, как раз, видимо, ввиду его свежести, этот стандарт нигде не найти бесплатно. По крайней мере, мне этого сделать не удалось.
Официальная страница.

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

Уточнения, дополнения и полезные ссылки приветствуются)

UPD: очень познавательный комментарий, спасибо lkochetova

UPD1: совесть меня таки замучила, и в статье больше не будет висеть прямых ссылок на скачивание стандартов, не распространяемых свободно. Если они вам понадобятся — нагуглить не составит труда.

UPD2: также смотрите статью Документирование по ГОСТ 34* — это просто с подробным разбором отечественных стандартов на проектную документацию.

Виды программных документов. Документация, создаваемая в процессе разработки программных средств.

При
разработке ПС создается большой объем
разнообразной документации. Она
необходима как средство передачи
информации между разработчиками ПС,
как средство управления разработкой
ПС и как средство передачи пользователям
информации, необходимой для применения
и сопровождения ПС. На создание этой
документации приходится большая доля
стоимости ПС.

Эту
документацию можно разбить на две
группы:

Документы
управления разработкой ПС.
Документы,
входящие в состав ПС.

Документы
управления разработкой ПС,
протоколируют процессы разработки и
сопровождения ПС, обеспечивая связи
внутри коллектива разработчиков и между
коллективом разработчиков и менеджерами
— лицами, управляющими разработкой. Эти
документы могут быть следующих типов:

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

Документы,
входящие в состав ПС,
описывают программы ПС как с точки
зрения их применения пользователями,
так и с точки зрения их разработчиков
и сопроводителей (в соответствии с
назначением ПС). Здесь следует отметить,
что эти документы будут использоваться
не только на стадии эксплуатации ПС (в
ее фазах применения и сопровождения),
но и на стадии разработки для управления
процессом разработки (вместе с рабочими
документами) — во всяком случае они
должны быть проверены (протестированы)
на соответствие программам ПС. Эти
документы образуют два комплекта с
разным назначением:

Пользовательская документация программных средств.

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

Следует
различать две категории пользователей
ПС:

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

Администратор
ПС управляет
использованием ПС ординарными
пользователями и осуществляет
сопровождение ПС, не связанное с
модификацией программ. Например, он
может регулировать права доступа к ПС
между ординарными пользователями,
поддерживать связь с поставщиками ПС
или выполнять определенные действия,
чтобы поддерживать ПС в рабочем состоянии,
если оно включено как часть в другую
систему.

Состав
пользовательской документации для
достаточно больших ПС:

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

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

Документация на программное обеспечение — это… Что такое Документация на программное обеспечение?

Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом^[1].

Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате^[1].

Типы документации

Существует четыре основных типа документации на ПО:

архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО
техническая — документация на код, алгоритмы, интерфейсы, API
пользовательская — руководства для конечных пользователей, администраторов системы и другого персонала
маркетинговая

Архитектурная/проектная документация

Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так?» Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.

Техническая документация

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

Пользовательская документация

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.

Маркетинговая документация

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

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

Примечания

↑ ¹ ² ГОСТ Р ИСО/МЭК 15910-2002 — Процесс создания документации пользователя программного средства
↑ ГОСТ 19781—90 Единая система программной документации. Обеспечение систем обработки информации программное

См. также

Ссылки

Пользовательская документация — Computer Science Wiki

Из Википедии о компьютерных науках

Перейти к навигации
Перейти к поиску

Этот контент используется с благодарностью с разрешения docdepartment.com ^[2]. Техническая документация — это документация, в которой описывается, как работает продукт или услуга. Например, документация по программному коду, технические спецификации и документация по API.

Пользовательская документация — это документация по продукту или услуге, предоставляемой конечным пользователям.Пользовательская документация предназначена для помощи конечным пользователям в использовании продукта или услуги. Это часто называют помощью для пользователей. Пользовательская документация — это часть общего продукта, поставляемого заказчику.

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

Пользовательская документация важна, потому что она дает пользователям возможность узнать:

как использовать программное обеспечение
особенности вашего программного обеспечения
советы и рекомендации по использованию вашего программного обеспечения
как решать типичные проблемы с вашим программным обеспечением

Без пользовательской документации пользователь может не знать, как делать указанные выше вещи.

Пользователи ожидают, что пользовательская документация будет включать:

Часто задаваемые вопросы
Видеоуроки
Встроенная помощь (например, подсказки и динамическое содержимое страницы)
Порталы поддержки

Что обычно включает в себя пользовательская документация? [Править]

Приведенный ниже список используется с благодарностью Департамента компьютерных наук Дартфорда ^[3].

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

Качество пользовательской документации может повлиять на скорость внедрения новой системы.Примеры должны включать такие методы, как файлы справки, онлайн-поддержка и печатные руководства.

Практические советы из реального мира [править]

Однажды я слышал слух о Стиве Джобсе. Согласно этому слуху, он сказал: «Если вам нужно написать руководство для своего программного обеспечения, вы сделали что-то не так». Я думаю, что суть этих слухов в том, чтобы сделать ваше программное обеспечение максимально простым в использовании. Однако хорошая пользовательская документация может способствовать успеху вашего продукта или помешать ему. Дизайн, представление и оценка вашей пользовательской документации — действительно важная часть разработки программного обеспечения.К сожалению, этой областью очень пренебрегают, поскольку разработчики программного обеспечения могут подумать, что это скучно.

Оценка пользовательской документации [править]

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

Стандарты [править]

Опишите важность пользовательской документации.
Оцените различные методы предоставления пользовательской документации.

Ссылки [править]

Техническая документация по разработке программного обеспечения: типы и инструменты

Время чтения: 18 минут

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

Проектная документация по этапам и назначению

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

Гибкий и водопадный подход

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

Водопад — это линейный метод с отдельными целями для каждой фазы разработки. Команды, использующие водопад, тратят разумное количество времени на планирование продукта на ранних этапах проекта.Они создают обширный обзор основных целей и задач и планируют, как будет выглядеть рабочий процесс. Команды Waterfall стремятся создать подробную документацию до начала любого из этапов проектирования. Тщательное планирование хорошо работает для проектов с небольшими изменениями или без них, поскольку оно позволяет точно составлять бюджет и оценивать время. Однако планирование водопада оказалось неэффективным для долгосрочного развития, так как оно не учитывает возможные изменения и непредвиденные обстоятельства на ходу.По данным 9-го глобального опроса PMI по управлению проектами, Agile-подход используется в своих проектах 71% организаций.

Схема цикла разработки Agile

Гибкий подход основан на командной работе, тесном сотрудничестве с клиентами и заинтересованными сторонами, гибкости и способности быстро реагировать на изменения. Основные строительные блоки гибкой разработки — это итерации; каждый из них включает планирование, анализ, проектирование, разработку и тестирование.Вначале гибкий метод не требует исчерпывающей документации. Менеджерам не нужно много планировать заранее, потому что все может меняться по мере развития проекта. Это позволяет осуществлять планирование точно в срок. Согласно одной из ценностей Agile Manifesto, поставив «работающее программное обеспечение над исчерпывающей документацией», идея состоит в том, чтобы создавать документацию с информацией, которая необходима для продвижения вперед, когда это имеет наибольший смысл.

Сегодня Agile является наиболее распространенной практикой в разработке программного обеспечения, поэтому мы сосредоточимся на практике документации, связанной с этим методом.

Виды документации

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

В соответствии со следующими классификациями.

Программная документация, наиболее часто используемая в Agile проектах

Всю документацию по программному обеспечению можно разделить на две основные категории:

Документация по продукту
Технологическая документация

Документация по продукту описывает разрабатываемый продукт и дает инструкции по выполнению с ним различных задач.Как правило, документация по продукту включает требования, технические спецификации, бизнес-логику и руководства. Существует два основных типа документации по продукту:

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

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

Основное различие между документацией по процессу и продукту состоит в том, что первая описывает процесс разработки, а вторая описывает продукт, который разрабатывается.

Продукт: Системная документация

Документация по системе

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

Документ о требованиях к продукции

Документ с требованиями к продукту или PRD предоставляет информацию о функциональных возможностях системы.Как правило, требования — это заявления о том, что система должна делать. Он содержит бизнес-правила, истории пользователей, сценарии использования и т. Д. Этот документ должен быть четким и не должен представлять собой обширную и сплошную стену текста. Он должен содержать достаточно информации, чтобы описать цель продукта, его особенности, функции, обслуживание и поведение.

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

Пример технической документации: документ с требованиями к программному обеспечению на одной веб-странице, созданный с использованием Atlassian Confluence , программного обеспечения для совместной работы с контентом

Вот основные рекомендации, которые следует включить в документ с требованиями к продукту:

Роли и обязанности .Начните свой документ с информации об участниках проекта, включая владельца продукта, членов команды и заинтересованных лиц. Эти детали прояснят обязанности и сообщат о целевых целях выпуска для каждого из членов команды.
Цели команды и бизнес-задача . Кратко опишите наиболее важные цели.
Предпосылки и стратегическое соответствие . Кратко объясните стратегическую цель ваших действий. Почему вы создаете продукт? Как ваши действия влияют на разработку продукта и соответствуют целям компании?
Предположения. Создайте список технических или бизнес-предположений, которые могла бы иметь группа.
Пользовательские истории. Перечислить или связать пользовательские истории, необходимые для проекта. Пользовательская история — это документ, написанный с точки зрения человека, использующего ваш программный продукт. История пользователя — это краткое описание действий клиентов и результатов, которых они хотят достичь.
Критерии приемки. Это условия, которые указывают на завершение пользовательской истории. Основная цель критериев приемлемости — определить удовлетворительный результат для сценария использования с точки зрения конечного пользователя.Прочтите нашу специальную статью о критериях приема, чтобы узнать больше.
Взаимодействие с пользователем и дизайн . Свяжите со страницей исследования дизайна и каркасы.
Вопросы. По мере того, как команда решает проблемы по ходу проекта, у них неизбежно возникает много вопросов. Хорошая практика — записывать все эти вопросы и отслеживать их.
Не работает. Составьте список того, что вы не делаете сейчас, но планируете сделать в ближайшее время. Такой список поможет вам организовать командную работу и расставить приоритеты.

Сделайте всю эту информацию более полной, используя следующие методы:

Используйте ссылки и якоря . Они помогут вам упростить чтение и поиск документа, поскольку читатели смогут постепенно понимать информацию. Например, вы можете предоставить ссылки на интервью с клиентами и привязки к предыдущим обсуждениям или другую внешнюю информацию, связанную с проектом.
Используйте инструменты построения диаграмм , чтобы лучше сообщить о проблемах вашей команде.Люди более склонны воспринимать информацию, глядя на изображения, чем читая обширный документ. Различные визуальные модели помогут вам выполнить эту задачу и более эффективно обозначить требования. Вы можете включать диаграммы в процесс создания требований, используя следующие программные инструменты построения диаграмм: Visio, Gliffy, Balsamiq, Axure или SmartArt в Microsoft Office.

Пользовательский интерфейс Проектная документация

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

Документацию UX можно разделить на этапы. Этап исследования включает:

Персоны пользователей
Пользовательский сценарий
Карта сценария
Карта истории пользователя
Руководство по стилю UX

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

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

Карты сценариев используются для компиляции существующих пользовательских сценариев в единый документ. Карты сценариев показывают все возможные сценарии, доступные в данный момент. Основная цель карты сценария — отобразить все возможные сценарии для каждой отдельной функции, а также пересекающиеся этапы сценария.

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

Пример карты пользовательской истории с разбивкой на выпуски

Источник: realtimeboard.com

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

На этапе прототипирования и проектирования , UX-дизайнер часто работает с результатами и обновляет документацию наравне с другими членами команды, включая владельца продукта, UI-дизайнеров и команду разработчиков. Наиболее распространенные документы, составляемые на этих этапах:

Карты сайта
Каркасы
Мокапы
Прототипы
Схемы потоков пользователя или путь пользователя
Отчеты тестирования юзабилити

Карта сайта / продукта — это визуальная схема, которая представляет связь между всеми страницами продукта.Карта помогает всей команде визуализировать структуру веб-сайта или приложения и связи между страницами / функциями. Создание карты сайта — это часть построения информационной архитектуры.

Пример структуры карты сайта

Источник: uxforthemasses.com

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

Схема работы пользователей приложения поиска работы

Источник: medium.com

Каркасы — это эскизы будущего пользовательского интерфейса. По сути, каркасы — это схемы, которые показывают, как расположить элементы на странице и как они должны себя вести. Но макеты не показывают, как должны выглядеть эти элементы.

Пример каркаса для мобильного приложения Peekaboo

Источник: gallery.wacom.com

Макет — это следующий этап проектирования продукта, показывающий реальный внешний вид продукта. По сути, макеты — это статические изображения, представляющие конечный дизайн продукта.

Прототип — это макет, с которым вы можете взаимодействовать: нажимать несколько кнопок, перемещаться между разными страницами и так далее. Прототип можно создать в таком инструменте прототипирования, как Sketch или MockFlow.Используя шаблоны, дизайнеры UX могут создавать интерактивные макеты на ранних этапах разработки, которые будут использоваться для тестирования удобства использования.

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

Документ архитектуры программного обеспечения

Проектная документация архитектуры программного обеспечения

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

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

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

Описание User Story. Свяжите истории пользователей со связанными бизнес-процессами и связанными сценариями. Вам следует избегать технических подробностей в этом разделе.

Подробности решения. Опишите предполагаемое решение, перечислив запланированные услуги, модули, компоненты и их важность.

Схематическое изображение решения. Определите схемы, которые необходимо создать, чтобы помочь понять и передать структуру и принципы проектирования.

Схема архитектуры веб-приложения Azure

Источник: docs.microsoft.com

Исходный код документа

Документ исходного кода — это технический раздел, в котором объясняется, как работает код. Хотя в этом нет необходимости, следует охватить аспекты, которые могут вызвать наибольшую путаницу.Основными пользователями документов с исходным кодом являются инженеры-программисты.

Документы с исходным кодом могут включать, но не ограничиваются, следующие сведения:

Фреймворк генерации HTML и другие применяемые фреймворки
Тип привязки данных
Шаблон проектирования с примерами (например, модель-представление-контроллер)
Меры безопасности
Прочие модели и принципы

Постарайтесь сделать документ простым, сделав короткие разделы для каждого элемента и поддерживая их краткими описаниями.

Документация по обеспечению качества

В Agile есть разные типы тестовых документов. Мы выделили самые распространенные:

План управления качеством
Стратегия тестирования
План испытаний
Технические характеристики тестового корпуса
Контрольные листы испытаний

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

Стратегия тестирования — это документ, описывающий подход к тестированию программного обеспечения для достижения целей тестирования. Этот документ включает информацию о структуре команды и потребностях в ресурсах, а также о том, что следует расставить по приоритетам во время тестирования. Стратегия тестирования обычно статична, так как стратегия определяется для всего объема разработки.

План тестирования обычно состоит из одной или двух страниц и описывает, что следует тестировать в данный момент.Этот документ должен содержать:

Список функций для тестирования
Методы испытаний
Таймфреймы
Роли и обязанности (например, модульные тесты могут выполняться командой QA или инженерами)

Спецификации тестового примера Документ — это набор подробных действий для проверки каждой особенности или функциональности продукта. Обычно команда QA составляет отдельный документ со спецификациями для каждой единицы продукта. Спецификации тестового набора основаны на подходе, изложенном в плане тестирования.Хорошая практика — упростить описание спецификаций и избежать повторений тестовых примеров.

Контрольный список тестов — это список тестов, которые следует запускать в определенное время. Он показывает, какие тесты завершены, а сколько не удалось. Все пункты в контрольных листах теста должны быть определены правильно. Попробуйте сгруппировать контрольные точки в контрольных списках. Такой подход поможет вам отслеживать их во время работы и не потерять их. Если это помогает тестировщикам правильно проверить приложение, вы можете добавить комментарии к своим точкам в списке.

Техническое обслуживание и справочное руководство

В этом документе должны быть описаны известные проблемы с системой и способы их решения. Он также должен представлять зависимости между различными частями системы.

Документация по API

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

Документация по API

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

Продукт: Пользовательская документация

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

конечных пользователей
системные администраторы

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

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

Часто задаваемые вопросы
Видеоуроки
Встроенная поддержка
Порталы поддержки

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

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

Функциональное описание — описывает функциональные возможности продукта. Большая часть этого документа создается после консультации с пользователем или владельцем.
Руководство системного администратора — объясняет различные типы поведения системы в разных средах и с другими системами. Он также должен содержать инструкции по устранению неисправностей.

Технологическая документация

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

Планы, сметы и графики. Эти документы обычно создаются до начала проекта и могут изменяться по мере развития продукта.

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

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

Стандарты. Раздел о стандартах должен включать все стандарты программирования и UX, которых команда придерживается на протяжении всего проекта.

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

Основная цель технологической документации — уменьшить объем системной документации. Для этого напишите минимальный план документации. Составьте список основных контактов, дат выпуска и ваших ожиданий с предположениями.

Дорожные карты Agile-продуктов

Дорожные карты продукта

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

Есть три типа дорожных карт продукта, которые используются производственными группами Agile:

Стратегическая дорожная карта
Дорожная карта технологий или ИТ
План выпуска

Стратегическая дорожная карта — это стратегический документ высокого уровня, который содержит общую информацию о проекте. В стратегических дорожных картах обычно указываются видение и долгосрочные цели.В случае гибкой разработки продукта дорожная карта может быть разбита на темы. Темы — это несколько задач, которые должна выполнить команда и которые каким-то образом связаны. Например, тема может звучать как «повысить скорость загрузки страницы», что влечет за собой несколько действий.

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

Пример дорожной карты стратегического программного обеспечения

Источник: productplan.com

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

Пример дорожной карты технологии

Источник: hutwork.com

План выпуска используется для установки жестких сроков выпуска выпусков. План выпуска должен быть ориентирован на фактические сроки без указания деталей выпуска.

Пример плана выпуска

Источник: productplan.com

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

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

Инструмент общего назначения

Существует бесчисленное множество инструментов для совместной работы для команд разработчиков программного обеспечения. Они могут помочь сформулировать требования, поделиться информацией и документировать функции и процессы:

Atlassian Confluence — самый популярный инструмент для совместных проектов, в котором есть вся экосистема для управления требованиями к продукту и написания документации.Confluence известен стабильной вики-системой и эффективным интерфейсом управления пользовательскими историями.
Document 360 — это база знаний самообслуживания / платформа документации по программному обеспечению, разработанная для продуктов «Программное обеспечение как услуга».
ai — это инструмент для совместного создания, хранения документации, обмена данными и использования вики-системы. Документация интерактивна, что означает, что разработчики могут встраивать блоки или фрагменты кода прямо в документ и делиться им одним щелчком мыши. Закончив редактирование документации, вы можете сохранить ее в формате PDF или markdown и опубликовать на любой другой платформе.
Github не нуждается в представлении, за исключением тех, кто хочет использовать его для документации по программному обеспечению. Он предоставляет вам собственную вики-систему и позволяет конвертировать вашу документацию в привлекательные витрины веб-сайта.

Редакторы Markdown

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

Специальные инструменты для дорожной карты

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

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

Инструменты для документации UX

Самыми популярными инструментами для разработки пользовательского интерфейса являются инструменты для создания прототипов, которые помогают создавать эскизы, макеты, каркасы и интерактивные прототипы:

Sketch — это простой, но мощный инструмент векторного дизайна с веб-приложением и настольным клиентом Mac. Sketch популярен и довольно прост, предлагая достаточно возможностей для проектирования интерфейсов.
InVision — один из самых популярных инструментов для создания прототипов. InVision славится своими функциями совместной работы и кроссплатформенными возможностями, что делает его отличным инструментом для разработки будущих интерфейсов.
UXPin — это инструмент для проектирования Mac и Windows, который позволяет создавать любые типы чертежей. Вы также можете загрузить свои эскизы или каркасы из других продуктов и сделать из них интерактивный прототип.
Adobe XD — где XD означает опыт дизайна.Продукт ориентирован на UX-специалистов. Это позволяет дизайнерам создавать прототипы с высокой точностью и делиться ими через приложение.

Инструменты для документации API

Чаще всего процесс создания документации API автоматизирован. Программисты или технические писатели могут писать документацию вручную или использовать генераторы документации API:

Swagger — это бесплатный программный сервис с самодокументированием, предназначенный для создания и обновления веб-сервисов и API RESTful.
RAML 2 HTML — это простой генератор документации, использующий спецификации RAML.

Образцы и шаблоны программной документации

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

umkc.edu — список различных документов для тестирования, архитектуры, требований и планов.
шаблонов Atlassian Confluence. Atlassian предоставляет готовые шаблоны проектной документации общего назначения со своим продуктом.
strongqa.com — шаблоны документации для специалистов по контролю качества. К ним относятся контрольные списки тестирования, шаблоны дымового тестирования, планы тестирования и многое другое.
ReadySET — это большая библиотека шаблонов документации по программному обеспечению в HTML, которая включает документы планирования, архитектуру, дизайн, требования, тестирование и многое другое.
ReadTheDocs — это универсальный шаблон, созданный на платформе ReadTheDocs, содержащий инструкции по написанию каждого типа документа, который может вам понадобиться, от архитектуры и диаграмм UML до руководств пользователя.

Как писать документацию по программному обеспечению: общие советы

Существует несколько общих практик, которые следует применять ко всем основным типам документации, которые мы обсуждали выше:

Напишите достаточно документации

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

Документирование — непрерывный процесс

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

Документация — совместная работа всех членов команды

Гибкий метод основан на совместном подходе к созданию документации. Если вы хотите повысить эффективность, опросите программистов и тестировщиков о функциях программного обеспечения. Затем, после того как вы написали некоторую документацию, поделитесь ею со своей командой и получите отзывы. Чтобы получить больше информации, попробуйте комментировать, задавать вопросы и поощрять других делиться своими мыслями и идеями.Каждый член команды может внести ценный вклад в создаваемые вами документы.

Нанять технического писателя

Если можете, стоит нанять сотрудника, который позаботится о вашей документации. Человек, который обычно выполняет эту работу, называется техническим писателем. Технический писатель с инженерным образованием может собирать информацию от разработчиков, не требуя от кого-то подробного объяснения того, что происходит. Также стоит включить в команду технического писателя, разместив этого человека в одном офисе, чтобы наладить тесное сотрудничество.Он или она сможет принимать участие в регулярных встречах и обсуждениях.

Использовать перекрестные ссылки

Используйте перекрестные ссылки между документами, будь то страницы продуктов или руководства пользователя. Правильная навигация по документации важна для правильного понимания читателем предмета. Такую практику можно считать пользовательской, но для документации вашего проекта.

Не игнорируйте глоссарии

Документация может быть предназначена для внутреннего или внешнего использования.В случае внешних документов лучше предоставить четкое объяснение каждого термина и , его конкретное значение в проекте. Документация должна сообщать идеи на понятном языке, чтобы установить lingua franca между заинтересованными сторонами, внутренними членами и пользователями.

Заключительное слово

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

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

Пользовательская документация — COPR-документация

Этот раздел содержит информацию для пользователей Copr Build System. Вы можете найти работающий экземпляр Copr на http://copr.fedorainfracloud.org/.
Вас также могут заинтересовать Документация и материалы для разработчиков.

Типы исходного кода сборки

Copr поддерживает несколько типов источников сборки.

URL-адресов

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

Вы также можете просто ввести URL-адрес файла .spec rpm (метаданные пакета), который описывает пакет без
включая фактические источники сборки. Исходники сборки снова доступны на общедоступном сервере по https,
затем будет загружен COPR автоматически в процессе сборки SRPM.

Прямая загрузка

Если у вас есть файл .spec или srpm, хранящийся локально, вы можете использовать этот метод, чтобы загрузить его непосредственно в
COPR из командной строки (с помощью инструмента copr-cli) или через веб-интерфейс COPR.

SCM

Этот метод позволяет создавать пакеты RPM из любого репозитория Git, DistGit или SVN, содержащего допустимый файл .spec.
Единственный обязательный аргумент — Clone URL , и если целевой репозиторий помещает файл .spec вместе
с исходными кодами пакетов в корневом каталоге, и вы хотите собрать из главного HEAD, он будет просто работать.
Для более сложных случаев есть еще кое-что, что нужно настроить. Например. вы можете указать подкаталог
целевого репозитория, если именно в этом репозитории размещены исходные коды пакетов.См. Следующие
список для полного описания опции:

Тип : SCM-тип репозитория, на который указывает Clone URL (другими словами, следует ли использовать простой git или git svn для последующего клонирования).
URL клонирования : какой репозиторий мы должны клонировать для получения исходных текстов.
Committish : Какой тег, ветвь или фиксацию мы должны проверить из истории клонированного репозитория.По умолчанию HEAD основной ветки.
Подкаталог : Где должна выполняться последующая команда сборки SRPM (см. Ниже). Путь указывается относительно корня репозитория.
Файл спецификации : Путь к файлу спецификации относительно заданного подкаталога . Обратите внимание, что вы можете при желании привязать путь к / (например, /rpm/example.spec ). Если не
указанный файл .spec будет расположен автоматически.

Последняя необязательная настройка (кроме общей опции конфигурации сборки) — это метод сборки SRPM.Доступны четыре варианта:
об / мин , tito , tito test и составляют srpm :

rpkg : выбор по умолчанию и наиболее универсальный. Помимо сборки пакетов из любого репозитория Git или SVN,
он также поддерживает сборку непосредственно из любого репозитория DistGit.
Обратите внимание, что rpkg (а также tito ) — это не только инструмент для генерации SRPM, но и, по сути, полноценный менеджер пакетов.
которые вы можете использовать из командной строки для поддержки ваших пакетов.Вы можете узнать больше об этом инструменте здесь.

tito : надежный менеджер пакетов RPM с множеством функций, и если ваш проект управляется с помощью Tito, это инструмент, который вы хотите выбрать для генерации SRPM (который
одна из многих функций диспетчера пакетов). Когда этот параметр выбран, последний тег GIT пакета будет использоваться для создания SRPM. Обратите внимание, что эта утилита в настоящее время
нет поддержки для указания альтернативного файла .spec, что означает, что поле Spec просто игнорируется при использовании этой опции и.spec-файл всегда будет располагаться автоматически.
Обратите внимание, что основное различие между этим инструментом и rpkg заключается в том, что целевой репозиторий должен быть инициализирован с помощью tito init , прежде чем этот инструмент можно будет использовать.
построить из него SRPM. Вы можете прочитать больше здесь.

tito test : при выборе этой опции для построения SRPM снова будет использоваться утилита tito, но на этот раз Committish
указанное выше значение (или HEAD ветки master, если не указан Committish ) будет использоваться для построения SRPM.Это соответствует использованию переключателя --test для
tito , когда он вызывается для генерации SRPM.

make srpm : С помощью этого метода пользователь сам предоставит исполняемый сценарий, который будет использоваться для генерации SRPM. если ты
если вы хотите использовать этот метод, вам необходимо предоставить .copr / Makefile (путь относительно корня репозитория) с целью srpm
в вашем репозитории. В эту цель srpm вы можете поместить все, что потребуется для генерации SRPM.Вы можете использовать сеть и клонировать другую
репозиторий, вы можете устанавливать новые пакеты, и вы можете делать практически все, так как этот скрипт запускается с правами root внутри
фиктивный chroot. Обратите внимание, что он запускается в имитирующем chroot той же версии ОС, что и хост сборщика (обычно последняя выпущенная Fedora
версия). Цель Makefile вызывается так:

 make -f  /.copr/Makefile srpm outdir = "" spec = ""

Параметр spec — это то, что вы указываете в поле Spec File для исходной спецификации SCM и сценария.
выполняется в подкаталоге , который вы также можете указать в разделе исходного кода.Обратите внимание, что вы можете просто игнорировать
параметр файла spec в сценарии, если он не нужен. Параметр outdir указывает, куда поместить результирующий
SRPM, чтобы COPR мог найти и построить его впоследствии.

Пример того, что можно поместить в .copr / Makefile :

 $ cd myrepo
$ cat .copr / Makefile
об / мин:
    dnf -y установить тито
    tito build --builder = SomeBuilder --test --srpm --output = $ (outdir)

Обратите внимание, что другие инструменты ( tito и rpkg ) также запускаются в указанном подкаталоге .

PyPI

С этим типом источника вы можете создавать пакеты python прямо с https://pypi.python.org/pypi. COPR переводит эти
пакеты в пакеты src.rpm автоматически с помощью инструмента pyp2rpm.

RubyGems

Подобно типу источника PyPI, это позволяет создавать драгоценные камни из https://rubygems.org/. Инструмент для перевода пакетов
вот gem2rpm.

Custom (скрипт)

Этот тип источника использует пользовательский сценарий для генерации источников (которые позже
используется для создания SRPM).Для получения дополнительной информации см.
Пользовательский исходный метод.

Временные проекты

Если вы хотите, чтобы ваш проект copr автоматически удалялся через некоторое время
(поскольку это какой-то проект CI / CD, некоторые тестовые материалы и т. д.), вы можете установить
Параметр «удалить через дни» в веб-интерфейсе или в командной строке:
copr-cli создать свой-проект ... --delete-after-days 10

Веб-перехватчики GitHub

Webhooks позволяет автоматически запускать сборку.

Сначала вам нужно перейти в свой проект Copr, на вкладку «Пакеты» и определить какой-нибудь пакет.Единственный тип источника, который имеет смысл вместе с веб-перехватчиками, — это «SCM». Отметьте опцию «Восстановление веб-перехватчика». Вы можете нажать «перестроить» и проверить, действительно ли сборка работает.

Теперь вы можете перейти на вкладку «Настройка», а затем «Веб-перехватчики». Вот ваш URL-адрес веб-перехватчика в виде https://copr.fedorainfracloud.org/webhooks/github/// .

Затем в своем проекте GitHub перейдите в Настройки / Веб-перехватчики и службы. Нажмите кнопку Добавить веб-перехватчик.
Заполните поле URL-адреса полезной нагрузки указанным ранее URL-адресом.Задайте для других полей значения: content: application / json; отправить только push-событие; не секрет . Нажмите кнопку Добавить веб-перехватчик.

И в следующий раз, когда вы отправите что-нибудь в свой git, Copr автоматически пересобирает ваш пакет.

Интеграция со страницей

Для любого экземпляра страницы (включая src.fedoraproject.org) вы можете настроить автоматическое восстановление Copr и пометку pr / commit для новых изменений, поступающих в репозиторий страницы, и его открытых запросов на вытягивание.

Автоматическое восстановление

На стороне Pagure вам нужно установить Fedmsg на «активный» в настройках вашего проекта (в разделе «Хуки» почти внизу).В некоторых случаях
(например, src.fedoraproject.org), он может быть уже активен по умолчанию, поэтому вам даже не нужно выполнять этот шаг.

В Copr вам нужно определение пакета SCM, которое может быть таким же простым, как указание общедоступного URL-адреса клона удаленного репозитория Pagure, см. SCM
если вам нужны более подробные настройки. Также убедитесь, что установлен флажок «Auto-rebuild».

Теперь ваш пакет SCM будет перестраиваться при новых фиксациях в основном репо, а также в открытых PR.

Обратите внимание, что встроенные изменения, поступающие из запросов на вытягивание, фактически не помещаются в основной репозиторий copr.Вместо этого они помещаются в боковые репозитории.
имен : pr: . — идентификатор запроса на вытягивание, открытого в Pagure. В Fedora вы можете включить боковой репозиторий для проверки изменений с помощью:

 $ sudo dnf copr enable  / : pr:

PR / фиксация пометки

Если вы хотите, чтобы ваши коммиты и запросы на вытягивание в Pagure помечались результатами сборки для каждого изменения, перейдите к настройкам проекта в своем проекте Pagure.Тогда:

В разделе «Ключи API» создайте новый ключ API (проверьте параметры «Отметить…» ), если он еще не создан, и скопируйте его
В Copr перейдите в Настройки-> Интеграции и вставьте скопированный ключ API во второе поле в разделе «Pagure»
В первое поле вставьте URL-адрес проекта Pagure, который можно просто скопировать из адресной строки браузера, если вы находитесь на домашней странице проекта
Нажмите «Отправить», и все готово.

Multilib

В Copr вы не можете собрать пакет i386 в репозиторий x86_64 (также известный как
Multilib пакет), например, например в Кодзи. Вы можете построить для обоих
chroot-пары с несколькими библиотеками (например, fedora-31-x86_64 и fedora-31-i386 )
по отдельности, и пользователи могут включить оба репозитория мультииб-пар — так, в свою очередь
все созданные 32-битные и 64-битные пакеты будут доступны одновременно.

Если вы хотите автоматизировать это, укажите, что ваш проект должен быть
«Поддержка мультиблоков».Либо в командной строке:

 copr create --multilib = on [другие параметры]

или установите флажок на странице Project -> Settings web-UI.

Когда (а) эта функция включена для проекта и (б) проект также содержит
Multilib-pair chroots, соответствующая страница проекта веб-интерфейса copr также предоставит
Кнопка файлов репозитория Multilib (кроме обычной), чтобы пользователь мог их выбрать. На
кроме того, dnf copr enable / устанавливает Multilib
Repofile автоматически вместо обычного в системе с поддержкой Multilib.

Пользователи также могут вручную установить репо-файлы Multilib на
системы независимо от настроек проекта, эти репозитории могут, например, выглядит так:

 $ кот /etc/yum.repos.d/rhughes-f20-gnome-3-12.repo
[copr: copr.fedorainfracloud.org: rhughes: gnome-3-12]
name = Репозиторий Copr для f20-gnome-3-12, принадлежащий rhughes
baseurl = http: //copr-be.cloud.fedoraproject.org/results/rhughes/f20-gnome-3-12/fedora-$releasever-$basearch/
skip_if_unavailable = Верно
gpgcheck = 0
включен = 1

[копр: копр.fedorainfracloud.org:rhughes:gnome-3-12:ml]
name = Репозиторий Copr для f20-gnome-3-12, принадлежащий rhughes (i386)
baseurl = http: //copr-be.cloud.fedoraproject.org/results/rhughes/f20-gnome-3-12/fedora-$releasever-i386/
skip_if_unavailable = Верно
gpgcheck = 0
стоимость = 1100
включен = 1

Статусные значки

Хотите добавить такой значок:

на вашу страницу? Например. на GitHub README.md? Вы можете использовать эти URL:

https://copr.fedorainfracloud.org/coprs///package/ / status_image / last_build.png
https://copr.fedorainfracloud.org/coprs/g///package//status_image/last_build.png

И этот значок будет отражать текущий статус вашей посылки.

FAQ

Какова цель Copr? ¶

Copr — это система сборки, доступная каждому. Вы предоставляете src.rpm, а Copr предоставляет репозиторий yum. Copr можно использовать для восходящих сборок, для непрерывной интеграции или для предоставления репозитория yum для пользователей вашего проекта, если ваш проект еще не включен в стандартные репозитории Fedora.

Для начала вам понадобится учетная запись FAS.

Что я могу построить в Copr? ¶

Вы соглашаетесь не использовать Copr для загрузки программного кода или других материалов.
(«Материал»):

вы не имеете права загружать или использовать, например Материалы, которые
нарушает права третьих лиц на интеллектуальную
собственность или другие применимые законы;
полностью или частично регулируется лицензией, не содержащейся в
список допустимых лицензий для Fedora, который в настоящее время находится по адресу
https: // fedoraproject.org / wiki / Licensing, поскольку этот список может быть
время от времени пересматривается Советом Fedora;
классифицируется как «Запрещенный объект» на
https://fedoraproject.org/wiki/Forbidden_items,
поскольку эта страница может время от времени изменяться Fedora
Совет;
предназначен для вмешательства, отключения, перекрытия, повреждения,
нарушить или нарушить инфраструктуру Copr или Fedora Project;
нарушает любые правила или руководящие принципы проекта Fedora, особенно Кодекс поведения проекта Fedora. Вы не , а не должны соблюдать Руководства по упаковке.; или
нарушает все применимые законы и правила.

Вы несете ответственность за проверку лицензий и убедитесь, что вы можете сделать получившееся репо yum общедоступным.

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

Было бы неплохо, если бы вы указали лицензию ваших пакетов в описании или инструкциях по установке.

Пакеты в Copr do не должны следовать
Рекомендации по упаковке Fedora,
хотя им рекомендуется это делать. В частности, модули ядра
могут быть построены в Copr, если они не нарушают лицензию
требования в пункте 2. выше.

Как я могу включить репозиторий Copr? ¶

См. Как включить репо.

Как я могу упаковать программное обеспечение как RPM? ¶

Есть несколько руководств:

Могу ли я собирать для разных версий Fedora? ¶

Да.Просто нажмите вкладку «Редактировать» в своем проекте и выберите несколько chroot-файлов, например «Fedora-19-x86_64» и «fedora-18-x86_64». После этого, когда вы отправите src.rpm, ваш пакет будет построен для обеих выбранных версий Fedora.

Вы также можете строить для EPEL.

Можно еще репозиториев yum? ¶

Да. У каждого пользователя может быть более одного проекта, и у каждого проекта есть один репозиторий yum, точнее говоря, один репозиторий на chroot.

Могу ли я отправить несколько сборок одновременно? ¶

Да.Просто разделите их пробелом или новой строкой, но имейте в виду, что мы не гарантируем порядок сборки.

Что происходит, когда я пытаюсь собрать пакет с тем же номером версии? ¶

Ничего особенного. Ваш пакет будет снова собран заново.

Могу ли я зависеть от других пакетов, которых нет в Fedora

Страница не найдена · GitHub Pages

Файл не найден

Сайт, настроенный по этому адресу, не
содержать запрошенный файл.

Если это ваш сайт, убедитесь, что регистр имени файла соответствует URL-адресу.
Для корневых URL (например, http://example.com/ ) вы должны предоставить
index.html файл.

Прочтите полную документацию
для получения дополнительной информации об использовании GitHub Pages .

Пн	Вт	Ср	Чт	Пт	Сб	Вс
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	31