[Devel-conf] документация alterator (was: Набор тестов для конфигуратора)

[Vitaly Ostanin]

Grigory Batalov пишет:
> On Fri, 21 Mar 2008 18:32:35 +0300, Stanislav Ievlev wrote:
> 
>> ТЗ вырастет из TODO ;)
> 
>   В TODO написано, что это "Планы по развитию alterator":
>   http://freesource.info/wiki/AltLinux/Sisyphus/Alterator/todo
>   Планы по развитию - это не техническое задание.
> 
>   http://freesource.info/wiki/AltLinux/Sisyphus/Alterator
> 
>   Документация по альтератору ужасающая. Несмотря на обилие примеров и цитат
>   кода на scheme, она не даёт ответ на вопрос: "Зачем всё это нужно?"

Вообще документации должно быть 2 - справочная (API docs) и
developer guide (руководство разработчика).

Примерное содержание dev guide:

* Что такое alterator-fbi
* Как установить и запустить
* Как написать модуль для alterator-fbi
* Рекомендуемый layout каталогов при разработке
* Структура простого модуля
* Описание html со ссылками на справочную документацию
* Описание структуры бакенда, типовые функции list, read, write,
new, delete, constraints
* Появление своего модуля в меню alterator
* Краткое описание programming style в бакенде, тонкости
scheme-образных конструкций (например, забытый print "()")
* Запуск и отладка своего модуля
* Описание многостраничных модулей, как работают переходы
* Расширение типовых функций list, read и т.д. для работы с
несколькими формами/типами запросов
* Как запускать программы из бакенда, чтобы alterator не сломался
* Подключение переводов
* Сборка модуля в rpm

Все упомянутые widgets должны сопровождаться ссылками на справочную
документацию. Примеры кода бакенда желательно дублировать, если код
в примере на awk, рядом надо привести пример аналогичного на shell.

Ещё хорошо бы описать типовые задачи:

* Вывод объектов в динамические таблицы
* Редактирование объектов после выбора в динамической таблице
* Передача точных значений объектов из строки динамической таблицы в
бакенд
* Прогресс бар
* Вывод stdout/stderr запущенной из бакенда программы в html

>   Сейчас этой документацией может воспользоваться только Владислав Завьялов,
>   т.к. он участвует в развитии платформы. А что делать писателям модулей?
>   Как получить представление о платформе, не влезая в дебри scheme?
> 
>   Почему все разделы вывалены на одну страницу? Откуда мне знать, что
>   нужно зайти в четвёртый (!) блок ссылок с названием FBI?
> 
>   Почему в документации нет ни одной картинки? (Скриншоты "hello, world"
>   не в счёт, но даже они убогие.)
> 
>>>  >   Не пора ли нам замахнуться на планирование разработки нашего альтератора?
>>>
>>> Так и ТЗ давно пора написать, но некому.
> 


-- 
Regards, Vyt
mailto:  vyt на altlinux.org
JID:     vitaly.ostanin на gmail.com

----------- следующая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : signature.asc
Тип     : application/pgp-signature
Размер  : 252 байтов
Описание: OpenPGP digital signature
Url     : <http://lists.altlinux.org/pipermail/devel-conf/attachments/20080325/30694be4/attachment-0002.bin>