Работа над документацией MS2, срок – до MODXpo
Привет, друзья!
Благодаря энтузиазму, упорству и трудолюбию Василия Наумкина в 2012 году мы получили инструмент (на деле ворох таких инструментов), сильно облегчающий жизнь разработчика. Я говорю о miniShop2 и дополнениях к нему.
Несмотря на успех первой версии, вторая версия стала прорывом и позволила случиться тому, что есть. Плагины для свойств и грамотная архитектура данного компонента, способствующая легкому добавлению новых функций и изменению стандартного поведения, позволила другим разработчикам создать уже 100 дополнений и расширений для оплаты, доставки, скидок и др. В магазине modstore.pro продаются и другие нужные дополнения для работы с сайтом, но поезд тронулся после успеха miniShop. И это круто!
Продолжим...
Опыт и практика показали, что модель построения такой экосистемы вокруг главного продукта оказалась выигрышной. Насколько экосистема выгодна с точки зрения прибыли, я не берусь судить, для меня важно, как это технически было достигнуто и какую пользу это принесло сообществу.
О создании и особенностях miniShop2, построении экосистеме вокруг него я буду рассказывать этой осенью в Мюнхене на международной конференции MODX разработчиков – MODXpo 2015.
А теперь непосредственно к теме.
miniShop2 славится одним недостатком – отсутствием цельной, собранной в одном месте, документации. Никто никого не обвиняет, работа над документацией иногда отнимает сил и времени больше, чем сама разработка. И если разработку еще иногда оплачивают заказчики (прямо или косвенно), то платить за документацию желающих нет вовсе. Тем не менее главным условием участия темы доклада в конференции было обещание предпринять силы, чтобы исправить проблему с документацией.
Глупо рассказывать аудитории о продукте, который они потом попробуют, и затем сообщить: «Извините, ребята, документации у нас нет на английском, на русском тоже нет, изучайте как хотите по топикам в сообществе». Поэтому пора предпринимать меры, еще успеваем.
План действий
Учитывая существование главного репозитория проекта у Василия, форка у команды Simple Dream, где разрабатываются новые функции согласно утвержденным планам, требуется унифицировать процесс работы над проектом и документацией.
Я предлагаю создать на GitHub отдельную организацию (вернее я уже создал – github.com/miniShop2), куда добавить участников проекта. В организации легче настроить управление доступом к отдельным репозиториям, легко создать команду по интересам с настройкой доступа. Аргументы понятны и сильны. В дальнейшем это позволит создавать дополнительные репозитории для сопутствующих проектов (вынести оплату PayPal в отельный бесплатный модуль на равне с остальными, учитывая что с 2.4 позволяет указывать зависимости к пакету одной строкой). Сам проект перенести из репозитория Василия в репозиторий данной организации, соответственно форки придется создавать наследуя репозиторий организации.
Документацию к проекту я предлагаю сделать в виде сайта на GitHub, используя GitHub Pages и Jekyll. Я так уже делал для проекта Gitify – github.com/modmore/Gitify/tree/gh-pages (я перевел документацию на 100%, скоро опубликую первую статью из анонса для ожидающих ;).
Работа над документацией буду вести совместно с заинтересованными лицами, перевод на английский планируется либо после завершения документации на русском, либо параллельно, по мере готовности страниц на русском. Так же договорился с англоязычными участниками MODX сообщества о помощи в вычитке и корректировке перевода.
Еще один путь – использовать docs.modx.pro, но репозиторий с документацией управляется только одним человеком, что создает определенные неудобства работающих над документацией. Владельцу репозитория это так же доставят неудобств постоянные просьбы слить ветку.
Такие мысли и соображения у меня. Предложения, претензии, замечания высказывайте в комментариях, пожалуйста.
P.S. Вопросы или преложения насчет предстоящей конференции в Мюнхене задавайте в личном порядке, пожалуйста.
Комментарии: 40
Авторизуйтесь или зарегистрируйтесь, чтобы оставлять комментарии.
Вот, уже есть все что нужно для счастья. Хоть 10 репозиториев создай — не поменяется ничего. Я за то, чтобы документацию причесать, но не верю что хоть что-то изменится радикально если это будет не docs.modx.pro а что-то еще.
По началу будет всплеск, затем заглохнет. Тут что-то другое нужно в плане прдхода к написанию, но что именно пока не готов сказать.
Может, не в полном объёме, может устарела местами, но не хуже других магазинов на MODX это точно. Очень много информации по ссылкам на анонсы новых версий — это подробнейший changelog, фактически.
Для примера, вот Shopkeeper
Вот ShopMODX (больше ничего похожего на документацию не смог найти)
Вот SimpleCart — здесь вроде побогаче, но и магазин платный
И по другим дополнениям документации тоже хватает — переводи не хочу.
Почему бы, для начала, не заняться тем, что есть?
— подтверждает мой тезис о том, что она раздроблена, разнесена по заметкам, что усложняет поиск и восприятие. Нет целостности, особенно для человека со стороны, который видит инструмент в первый раз.
С документацией у других компонентов для ИМ тоже все плохо, это факт, но это не повод ничего не делать.
Вот масса информации, ссылки собраны в одном месте — что еще нужно для начала работы? Как создание неких непонятных структур и привлечение не пойми кого ускорит процесс?
Мой опыт показывает, что работа выполняется быстрее, когда ей занимается один человек.
Мы можем смело сравнить как выпускался ms2.0 и ms2.1, когда им занимался один человек, и как сейчас выпускаются версии 2.2 и 2.3, когда там целая команда — ровно так же будет и с документацией.
Да и вообще, как что-то писать сегодня? По какой версии — по стабильной 2.1 или по бете 2.2, или по альфе 2.3?
На мой взгляд, перед написанием новой документации нужно привести в порядок сам miniShop2: обновить интерфейс, внести разные исправления, разобраться с заявленными ошибками на GitHub. И вот когда у нас будет чистенький опрятненький компонент — уже можно что-то писать, с новыми скриншотами.
— это утопия, или когда компонент будет полностью мертв. Изменения в живом проекте будут всегда, документировать разные версии тоже не проблема.
На miniShop2 понадобилось бы около месяца, если бы в один определённый момент сообщество выбрало рефакторинг, а не наращивание функционала.
А так мы имеем, что имеем.
Готовую документацию было бы здорово разместить и на docs.modx.pro — там уже много чего есть.
Fi1osofВы меня, конечно, извините, но это жесть.
Документация к проекту и так сейчас «в виде сайта на гитхаб».
Забавно читать, про данный «путь», как «ещё один».
Аргуметы притянуты за уши. Никто не мешает и никто не запрещает прямо сейчас брать и переводить (и причёсывать) текущую документацию и делать пуллреквесты.
Если это всё ради сообщества, то надо было сперва предложить автору обсуждаемого дополнения самостоятельно на свой аккаунт зарегистрировать организацию на гитхабе для его же дополнения, и где
А если уж:
, то не подавать это под видом обеспокоенности за свободное время одного занятого человека — автора проекта.
В конце надо было добавить — «Отказ Василия от авторства miniShop2 необязательно, но приветствуется».
Не, нуачо.
Как-то так между строк читается. Лицемерненько.
Если бы вы были более внимательным, то увидели бы, что я на MODXpo хочу рассказать, как круто в ms2 все сделано и как с этим удобно работать и к чему такой подход может привести (создание успешного магазина дополнений).
С автором и с теми, кто сейчас работает над проектом, я общался прежде, чем написать этот пост и подать заявку на конференцию.
Хотите жить в болоте — живите, но не заставляйте других копаться в нем же и упрекать в том, что они хотят, чтобы было лучше.
Я участвую в обсуждении. Если вы ожидали одних лишь одобрительных возгласов, то извините.
Это не злость. Это взгляд под другим углом.
Дак всё так. Но при этом к моему комменту это никак не относится.
По-моему вы увидели то, что захотели увидеть. А не то, что я написал. Сюда же относится и вот это утверждение:
Офигенный вывод. Именно это я и имел в виду, ага.
Если бы вы были более внимательным, то увидели бы, что суть моих претензий не к вашим начинаниям как таковым, а к тому, что на данный момент уже имеются все инструменты для преодоления описанных вами проблем. И вы хотите делать абсолютно то же самое, только под другим углом (и под собственным контролем, ага).
Ещё раз.
Конференция и популяризация — это круто, это здорово. Я всеми конечностями «за», без сарказма.
Но.
Репозиторий у проекта есть? Есть. Он открыт? Открыт. Зачем нужен новый репозиторий для проекта?
Сайт для документации есть? Есть. Репозиторий, из которого наполняется сайт с документацией, есть? Есть. Документация к проекту есть? Не особо? Так зачем нужен новый репозиторий? Заполняйте имеющийся!
И не надо рассказывать про упрёки, «вы все злые», «никому ничего не надо» (больная тема сообщества, все дела). Если же у вас сейчас появилось желание снова упрекнуть меня в излишней злости и желании жить в болоте, я задам вам пару вопросов. Ответьте на них, пожалуйста.
1. Какие из _уже_ имеющихся в сообществе инструментов не позволяют решить описанные вами проблемы с документацией?
2. Зачем нужен новый репозиторий для самого минишопа, который вы хотите сделать головны`м?
(чтобы он был под вашим контролем чтоли?)
Делайте форк, развивайте и возвращайте обратно в пуллреквестах. В чём проблема?
3. Почему вы называете необходимость делать пуллреквест в репозиторий с документацией «болотом»? Вы ведь именно это имели в виду, да? Если нет, то что принципиально нового вы готовы предложить, чтобы это нельзя было назвать «болотом»? Или ничего принципиально нового не будет? Тогда зачем вы занимаетесь дроблением? Делайте форк, дополняйте, переводите, возвращайте обратно в пуллреквестах. В чём проблема? Зачем дробить то, что уже и так есть?
В конечном счёте выглядит всё это как-то так:
вместо развития уже имеющихся инструментов (которые и были созданы для решения описанных вами же проблем) вы пытаетесь создавать точно такие же, под видом добавочной ценности, попутно «перехватывая» контроль над репозиториями. Что-то вроде «рейдерства» в мире opensource.
Я художник, я так вижу.
Вот если бы это сразу было в статье — я бы мимо прошёл и ни слова б не сказал. Но раз уж я уже начал, то ответьте, пожалуйста на вопросы выше.
Вопрос в другом, и он очень серьёзный — кто сегодня отвечает за развитие miniShop2? Кому присылать pull-request?
За версию 2.1 отвечаю я, она мне всем нравится, но чтобы двигаться дальше я хочу её отрефакторить. Пока этого не будет — я ничего не делаю.
За новые версии отвечает команда Simple Dream, которые с 01.02.2015 пишут новые функции. Стабильной версии и готовой документации, насколько я понимаю, нет до сих пор.
Двигаться дальше я не могу — мне некуда. Версии 2.2 и 2.3 уже заняты и подключаться к ним мне неинтересно, потому что я хочу переписать MS2, а не наращивать функционал. Переписывать версию 2.1 при наличии 2.2 и 2.3 тоже как-то странно. Да и какой у неё будет номер — 2.4 без функционала 2.2 и 2.3? Забавно.
Вот и сижу, жду, чем всё это закончится. Будут ли стабильные новые версии, которые можно переписать или нет? А если будут, буду ли я согласен с изменениями, которые туда внесли?
Единственный пока реальный вариант, на мой взгляд, снова взять разработку в свои руки и сделать платный форк miniShop2Plus или как-то так. Продавать его за большие деньги, оказывать поддержку, писать документацию и т.д.
Но это получается, что я только ms2Plus и буду заниматься, всю оставшуюся жизнь, а меня это что-то тоже не особо прельщает.
Первая версия miniShop2 была написана за 3 месяца, с нуля. Вместе с pdoTools, галереей, системой плагинов и прочими наворотами.
Новые версии пилят уже почти полгода. Это к вопросу о работе одиночек и организаций.
Насколько я вижу, представителей от SD здесь нет, да и Виталий Киреев твоё приглашение в новую организацию пока не принял. В мой репозиторий новые версии тоже никто не присылает.
Думаю, документацию стоит писать по нынешней версии 2.1, как она есть сейчас.
Если я буду её обновлять — доработать документацию будет проще, чем писать с нуля. Да и неизвестно, когда это будет и будет ли вообще.
Василий, открой тайну.
Сейчас они делают новые версии, и пока не закончат, мне некуда двигаться. Подключаться к ним я не хочу, потому что новый функционал без переработки старого кода мне не интересен — я много раз об этом говорил и повторяю снова.
Делать сейчас какую-то свою новую версию, без оглядки на их работу, будет некрасиво по отношению к вам, профинансировавшим новый функционал.
Так что, мне остаётся только ждать, чем закончится ваша краудфандинговая компания.
Как только скажут: «вот стабильные версии 2.2 или 2.3, вот описание изменений, вот примеры работы, кушайте на здоровье» — я смогу думать о рефакторинге уже всего проекта сразу.
Между прочим, типа стабильная версия 2.2-pl лежит в репозитории Argnist, но объявлений об этом никто не делал и в магазине её нет. Странно это всё.
Мы изменили то-то и то-то, это нужно использовать вот так-то, а если не получается — пишите сюда, мы всё исправим. Это как минимум.
Можно и несколько объявлений, как у версии 2.1: 1, 2, 3, 4, 5, 6.
А не
От таких объяснений у меня немного глаз дёргается.
Печально даже не то, что релиз 2.2-2.3 затягивается (это нормально). Обидно то, что ты, как автор, не видишь дальнейшего развития в рамках обновлений форкнутой версии, со всеми вытекающими (2 разных ветки, разный функционал, разные авторы, разные компетенции).
Вот он и минус opensource'а как такового
Вопрос только в том, как можно прийти к исходу с возвращением проекта в ваши руки? — при том факте, что на текущее расширение функционала, насколько я помню, деньги были успешно собраны, но при рефакторинге есть вероятность свести на нет все наработки SimpleDreams в этой области.
Что до стабильности… ну, не критики ради, а уведомления для — только на моей памяти в версиях были ошибки с: установкой и конфликтом со стабильной веткой, внеплановое отключение и откат опций, отключение расширенных ранее опций, конфликты с другими дополнениями minishop'a, пропажа изображений, цены и других параметров товаров. При том, что версия 2.2 и была заточена под эти самые опции товаров.
Повторюсь — я описываю все это не с позиции хейтера и прекрасно понимаю, что версии на стадии альфы/беты нужно тестировать и обкатывать. И в целом инициативу развития minishop'a стараюсь поддерживать и материально и идейно.
Но я пишу лишь с позиции того, что вижу постфактум: финансирование было собрано на радостных тонах, после чего вышла (на мой взгляд) слишком сырая версия, чтобы ставить ее на рабочие проекты, после чего любые оповещения о развитии были сведены к минимуму. И в таком состоянии прошел год.
В связи с таким развитием событий я и высказал свое мнение.
Теперь по пунктам.
1 — Я не отказывался от идеи отправлять документацию на docs.modx.pro, но на сейчас считаю не очень удобным необходимость напоминать или просить Василия смерджить каждый PR. А делать все у себя и мерджить потом одним большим куском тоже неправильно, так как смотреть километровые дифы ни у кого нет желания. А уж тем более разбираться потом, почему оно неправильно залилось на сайт.
2 — создавать репозиторий ради репозитория не имеет смысла. Идея моя шире и глубже и я о ней написал. Создание организации, выделение групп по интересам, создание дополнительных расширений в рамках одной организации — это задел на будущее.
3 — это моя эмоциональная реакция на тон ваших высказываний.
Да и одним куском тоже не проблема. Какие диффы, о чем речь? Сейчас в docs.modx.pro про сам miniShop2 нет ничего.
2. Про организацию, в очередной раз напоминаю — с февраля идёт разработка новых версий силами Simple Dream.
Настолько мощно идёт, что уже предлагают кому-нибудь заняться управлением проекта.
Мне кажется, тебе стоит предложить свои услуги там. Это реально может что-то изменить.
По второму пункту. Предлагать свои услуги там нет смысла, ибо у них свой коммерческий интерес и сомнения (или бесплатно на пожерствования или вложимся и будет продавать). Мой интерес, чтобы сообщество не страдало от конфликтов и разногласий между разработчками. Сначала документация, а потом видно будет.
Ну и + ко всему, если уж переносить куда-то документацию по modx, то, на мой взгляд, логично переносить туда же и документацию к дополнениям по нему. А это путаница как для разработчиков дополнений, выкладывающих их на modstore, так и дробления основного сайта документации docs.modx.pro
Поэтому напишу покороче.
Иван, вы назвали болотом имеющийся в сообществе подход по наполнению и ведению документации.
При этом реально ничего нового вы не предлагаете.
На деле же выйдет так, что вместо одного репозитория — будет 2. И они не будут взаимодополняемыми.
Плюс вы хотите перевести проект минишопа на другой аккаунт, который находится под вашим контролем.
Вопрос — зачем всё это?
Ну вот об этом же ни слова в топике нет. Поэтому совершенно обоснованно приношу свои вам извинения за беспочвенные обвинения.
Почему-то в этих строках читается завуалированное «Все плохие, а я Д'Артаньян.»
Как Вася выше же и написал — ему не сложно принимать пуллреквесты в документацию. Только принимать-то нечего. Ни вы, ни я документацию по минишопу не наполняли (я так вообще в документацию ничего не добавлял). Но при этом я не кричу о том, что вокруг одно болото, никто ничего не хочет делать и поэтому надо делать ещё репозитории с документациями. Смекаете?
По ms2 я действительно пока ничего не написал, но собираюсь это исправить в ближашее время. Тем не менее я привел в пример репозиторий с Gitify, где видны мои текущие результаты работы.
Всем привет. У нас действительно намечаются трудности с менеджментом и координацией проекта miniShop. Если есть энтузиасты — пишите мне в скайп evteev_andrey. Или на почту evteev@simpledream.ru. Мы быстро порешаем все насущные вопросы и дадим ходов проекту.