Разработка документации

Документация как центральный орган

Главная, как по мне, проблема Куспа, — это его децентрализованность. Это значит, что одна рука не ведает, что творит другая, а потом выясняется, что это уже давно всё сделано; а ноги вообще идут своим каким-то непонятным путем.

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

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

Когда документация выходит на сцену в разработке?

Вот к примеру, Байт хочет ввести тип для кортежей. Он пишет в #qsp_platform_dev свои планы, и начинается обсуждение в духе: "Какой символ использовать?", "Какие проблемы решает новый тип?" и т.д. На все вопросы рано или поздно находятся ответы, обсуждение к чему-то приходит, но всё это сейчас находится в чатике в виде разрозненных сообщений.

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

Я вот, к примеру, пишу пост-обобщение про тип кортежей, затем показываю его участникам в чате. Всё это дело правится, одобряется, пересматривается и в конце концов пост отправляется в документацию (скорее всего, материал пойдет в раздел языка QSP, где ему самое место).

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

Каким языком должна писаться документация?

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

У нас имеются:

• разработчики самого Куспа
• разработчики игр на Куспе

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

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

А бывает так, что и сами разработчики игр сами создают инструменты. Я почему-то уверен, что ребята из GLife были простыми разработчиками игр на QSP, а потом как-то умудрились додуматься до контроля версий GIT, что надо всю эту махину растаскивать по отдельным исходникам, даже расширение придумали для них — .qsrc. Я вот, к примеру, не знал об этом, и вляпал свое .qsps для расширения VS Code. В итоге у нас идет два разрозненных стандарта расширений для исходников, и какой из них "правильнее" — кто его знает. Скорее всего, придется поддерживать два типа.

Документация должна отсекать такие случаи и приводить к общему знаменателю. А чтобы в документации разобраться, нужно писать ее как можно более понятнее. А что такое "более понятнее" — фиг его знает!

Возможно, научпоп надо отдать на откуп евангелистам (Aleks Versus, к примеру, занимается этим на своем канале) и не сушить себе голову, а может, надо немного уменьшить градус техничности. Истина где-то рядом.

Структура документации

Сейчас написано мало и толком непонятно, как всё это структурировать.

Предлагаю сделать структуру пока что такой:

• QSP Foundation — о том, что это всё такое, зачем оно надо и т.д. Возможно, стоит вклинить туда этот пост
• Совместная разработка — статья о том, как заполнять документацию, чтобы не наступить друг другу на ногу. Скорее всего, название неудачное и надо его сменить
• Общий взгляд — сейчас это называется "Всё вместе". Здесь нужно показать, как все сущности стыкуются между собой
• язык QSP — спецификация языка, т.е. то, с чего по-идеи должен начинаться QSP и от чего наследуются остальные сущности
  • синтаксис — по-идеи, тут надо изложить полное синтаксическое дерево от значений до локаций в каком-то всем понятном формате. Я поглядываю в сторону EBNF с визуализацией, но это надо обсуждать
  • семантика — предопределенные переменные, процедуры, функции и т.п., что они означают и как работают
• Парсеры — раздел с парсерами
• Интерпретаторы (движки? Т.е. прослойка между парсерами и плеерами)
• Компиляторы (штуки, который преобразуют код QSP в нечто другое) — пока что мне известен только компилятор qsp-to-js Garret'а и qsp-to-twine ребят из GLife, но, возможно, их больше
• Плееры
• Разработка
  • Редакторы — краткое описание QGen, к примеру
  • Расширения для редакторов — краткое описание JAD и Qsp.FSharp.VsCode
  • Анализаторы
    • вот тот анализатор на C#
    • какой-то неизвестный анализатор на OCaml
• Персоналии — раздел, в котором перечислены разработчики экосистемы, кто чем занимается и к кому в случае чего обращаться. Друзей надо знать в лицо! Что-то вроде персоналии в IFWiki, но с разработчиками