Тип документов "Спецификация" / RFC
CHANGES
VERSION | DATE | DESCRIPTION OF CHANGE | AUTHOR |
---|---|---|---|
0.01 | 2020.06.04 | Начальная версия | zag |
Основные положения
Требуется разработать структуру документов, формализующих разрабатываемый фунционал, форматы данных. Такие документы служат в качестве отсылок из документации, а также в качестве объекта для обсуждения на этапе проработки задачи.
Структура документа
За основу предлагается взять шаблон, который описан ранее в блоге.
В него добавлена версия, которая может быть извлечена из блока =CHANGES
.
Заголовок: Техническое задание на разработку
Изменения
Основные положения
Release Notes
Терминология и Соглашения
Что необходимо сделать
Идеи и дополнения
Шаблон документа выглядит следующим образом:
=begin pod :pubdate('2020-06-05 13:00') :status('draft')
= :publishUrl('/rfc/rfc')
=TITLE Заголовок: Техническое задание на разработку
=AUTHOR
=CHANGES
=begin table
VERSION DATE DESCRIPTION OF CHANGE AUTHOR
==========|================|=========================|========
0.11 2020.06.04 B<что> было сделано L<zag>
возможно еще есть что
добавить
=head1 Основные положения
=head1 Release Notes
=head1 Терминология и Соглашения
=head1 Что необходимо сделать
=head1 Идеи и дополнения
=end pod
Отличительные качества "Спецификаций"
статус rfc ( черновик, отклонен, на рассмотреинии, принят, архив)
ТОС
Изменения в документе
Спецификация имеет постоянный адрес
Блоки спецификации могут быть опубликованы при указании у них даты публикации, спецификация конвертируется в поток постов в блоге и соответсвенно в rss.
В качестве источника для отметки активности (лога) выступают следующие части спецификации:
Элементы таблицы CHANGES
произвольные блоки с указанной датой публикации
Если элемент таблицы changes ссылается на блок, что является поводом для публикации блока в ленте rss. Дата публикации берется из поля
DATE
таблицыCHANGES
Что необходимо сделать
сделать шаблон RFC
прогон документа на понятливость
Как быть когда со временем кол-во RFC вырастает, как находить связанные RFC,
группировка актуальные - неактуальные
поиск по rfc, древовидный индекс, по ключевым словам
архивные RFC
Идеи и дополнения
Следующие материалы возможно стоит также добавить в шаблон:
User Stоries/ Задачи
Таблица с таймланами и майлстоунами
Таблица с оценками/голосованием заказчиков данного документа +/-1
Ссылки на смежные RFC / ссылки на статьи/ whitepapers
LINKS
https://medium.com/knerd/system-design-documents-at-knewton-rfcs-f8f31647e91
Template https://docs.google.com/document/d/1ItRLwOwVH8RFJFRTzlRxLUxydogC5x1uNV-FimkDFFU/edit
Пример SRS http://analyst.by/forum/dokumentaciya/kto-mozhet-podelitsya-shablonom-srs
Пример функциональных требований https://www.smartsheet.com/free-functional-specification-templates
PEP 1 -- PEP Purpose and Guidelines https://www.python.org/dev/peps/pep-0001/#what-is-a-pep