Тип документов "Спецификация" / 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

 ↑