Куда в Wiki разместить сложные примеры кода.
Для тех, кто в танке: http://wiki.qsp.su/ - новая справка по QSP.
Есть куча примеров кода (использование предмета на предмет, многомерные массивы, выкладывание предмета на любой локации с возможностью забрать и многие другие). Есть несколько готовых модулей.
Вопрос в том, куда разместить их в справке - можно в подраздел справки после “расширенных возможностей”, можно в отдельную параллельную структуру.
Плюсом первого варианта является то, что оглавление будет единое на всю Wiki.
Плюсом второго варианта является то, что оглавления не будут раздутыми и будут разделены описание платформы QSP и решение программистских задач.
В первом случае вовсе не обязательно “раздувать” оглавление. Если пунктов в разделе оглавления слишком много, то делается просто одна статья в которой всё перечисляется. Так же как, например, “список ключевых слов”.
Во втором случае, автору придётся постоянно скакать между двумя параллельными документами. Оператор он смотрит в справке, применение оператора в “примерах кода”… Если он скачает справку вместе с кугеном, то придётся держать два открытых окна справки вместо одного.
“Будет разделено описание платформы QSP и решение программистских задач” - а почему это плюс? Чем это лучше? Я вот вижу только создание путаницы и неудобства.
Я считаю, решения стандартных игровых задач обязательно должны быть в справке. Чтобы узнать, “как сделать разговор с персонажем”, “как сделать бой”, “как вставить картинку”, “как сделать действие по условию”, пусть автор откроет родную справку и сразу всё найдёт. Потому что он в любом случае в неё полезет, а если не найдёт, то скорее решит что это вообще в документации не описано.
И не нужно тащить в этот раздел всё подряд. Следует аккуратно выбрать самые востребованные задачи, переработать при необходимости соответствующие примеры кода и сопроводить их внятным описанием (большая часть сейчас вообще без описания). Тогда ничего захламлено не будет. Начать с перечисленного в FAQ, “вопросы по программированию”.
Что касается готовых подключаемых модулей, их следует собрать в отдельной статье. Их совсем немного, раздел для них не нужен.
Я придумал решение. Такие примеры будут отдельным неймспейсом (на читателей это всё равно не повлияет). Оглавление будет общим, но потом легко будет его выдернуть в отдельное, если потребуется.
Никакого смысла в этом не вижу, но на читателей действительно не повлияет.
Пока не увижу достаточного интереса к теме, не хочу на это всё время тратить. Подожду месяца два обратной связи по тому, что уже есть и что нужно добавить. :)