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

Уже которую неделю вижу в комментариях сообщения, мол «это нужно добавить в документацию», «а почему этого нет в документации» и подобные.

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

Сколько можно ныть в комментариях?
Считаешь, что нужно что-то добавить — добавь. Считаешь, что такая статья должна быть — напиши и пришли. Кто мешает?

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

В этом сообществе зарегистрировано несколько тысяч человек, при этом авторов документации всего 48. Хотите хорошие тексты — пишите их сами, инструмент для этого давно разработан и прекрасно работает.

За сим, впредь предлагаю всё нытьё о документации в комментариях минусовать.
Василий Наумкин
25 декабря 2016, 11:12
modx.pro
1
2 432
+26

Комментарии: 26

Павел Левин
26 декабря 2016, 01:27
+1
Мне не понравилось высказывание про дворников, это мы привыкли думать о них как об мусоро-уборочных людях, но смысл их в другом, ухаживать за двором или я ошибаюсь? Ведь природных явлений хватает, чтоб была потребность в дворниках, а люди довольно умны, чтоб отличить газон/асфальт от мусорной корзины. Да и такие временные хранилища как карманы, никто не отменял. Порой идешь по улице и видишь как подростающее поколение считает это нормой и естественным природным явлением. Печально. Крик души :)
    Дмитрий Вершинин
    26 декабря 2016, 07:27
    +2
    Как глубоко вы прочувствовали смысл поста :) И поколение — подрАстающее. Это я немного дворником поработал :)
      Павел Левин
      26 декабря 2016, 11:28
      +1
      Я дворником не работал, но в социальной гос структуре бывал (ЦСО 3,5 года). Здесь скорей всего уровень воспитания т.к. я с малых лет перестал выкидывать где попало, т.к. заметил, что совесть мучает — бросил, а ведь мог донести и выкинуть. Так и осталась привычка.

      Просто мне не все равно, а когда тебе не все равно, ты высказываешься, аналогично Василию. Ведь так?
      Это как документация, важная экологическая тема для данного сообщества. Хотя ассоциативный ряд представленный в посте мне не ясен, я читал много раз доку и не видел там свинарника, изначально пишет человек, который в этом хорошо разбирается и он пишет в мысленном инкубаторе, опуская маловажные моменты — это нормально.

      Вангую появление платных видео курсов в модсторе на тему «как создать магазин» и т.д.
      — ЗЫ: Да, ошибку допустил, мог проглядеть с телефона писал :)
        Владимир
        26 декабря 2016, 11:59
        0
        появление платных видео курсов в модсторе на тему «как создать магазин»
        пардон, просто хотел бы уточнить, вы негативно упоминаете «платных », как сам факт коммерческой составляющей в этой сфере? Т.е. лучше бы пони появились как бесплатные, так?
          Павел Левин
          26 декабря 2016, 12:39
          0
          Где именно негатив?
            Владимир
            26 декабря 2016, 12:43
            -2
            негатив в двоякости фразы
            Вангую появление платных видео курсов в модсторе на тему «как создать магазин» и т.д.
            , и вообще, в подаче мысли, если для вас это не очевидно, не факт, что вы передали остальным свой посыл однозначным для понимания.
              Павел Левин
              26 декабря 2016, 12:51
              0
              Ну это личное восприятие — я же делал это для мотивации, чтоб посадить семя идеи.

              Возможно некая общая негативная тенденция сообщества, лично я ничего не имею против платного расширения/дополнения, тем более оно идет с поддержкой и обновлениями, да и если готовое решение поможет сделать задачу быстрее и качественнее, то дополнительные средства на неё выделить можно — это же не десятки и сотни тысяч. Малый бизнес, он такой :)

              Люди разные и мнение разное, такое бывает.
                Владимир
                26 декабря 2016, 13:01
                0
                это личное восприятие
                — да, не спорю, интересно, кто как и я скорее негатив, чем мотивацию увидел? )) Риторический вопрос.
                Спасибо, я что хотел — ответ получил.

          Іван Клімчук
          26 декабря 2016, 23:49
          0
          Опоздали, уже веду работу в этом направлении — modcasts.video/ :)
            Павел Левин
            27 декабря 2016, 00:42
            0
            По дизайну, стоит поработать над визуальными границами :)
            В остальном хороший flat.

            По видео контенту — сами уроки, лично мне нравится формат лофтскул т.е. довольно сжатые уроки, хорошо продуманные и без лишней воды. Советую ;)
              Іван Клімчук
              27 декабря 2016, 00:54
              0
              Дизайн дело такое, хорошо когда его нет. Вернее когда он не чувствует, а просто удобен. Но к советам прислушался, спасибо.

              Про лофтблог знаю, еще есть ларакаст и друпализми (ценник адовый у них) и другие проекты, которые делают именно короткие ролики по существу. Уроков хватает в сети, но смотреть, как некий условный Петя полтора часа дрочит блог на MODX, у меня вызывает отвращение :)
                Павел Левин
                27 декабря 2016, 11:59
                0
                Я наверное представил не очень четкий пример =) за эталон я брал вот этот блок уроков.
                Еще интересные варианты есть в игровой форме от codeschool (встречал и русский аналог) т.е. они дают ролик, далее задание и ты должен выполнить его в рамках ресурса и так поэтапно. В таком варианте, не получится сказать себе, что «я посмотрел я все понял, давай дальше» обойдя тем самым практику.

                В целом концепция codeschool интереснее чем loftschool. Ведь если вспомнить с чего начинали ребята из лофтскула, то это были ролики на канале ютуба и «стримы» после основного рабочего дня, теперь же они смогли найти достаточное кол-во единомышленников и систематизировать свой бизнес процесс. Теперь работа на идею — это не их, только монетизация, рано или поздно все к этому приходят, но монетизация есть разная, агрессивная или мягкая с приманками :)

                Проявив интерес к начальному блоку курса, допустим некая база, можно ознакомить человека с общей концепцией и собственно дать привыкнуть к преподавателю (голос, манеры и т.д.). Добавив кучку роликов с кейсами (периодически), можно подогреть интерес к продуктам (допустим из модстора — особенно есть есть рефер ссылки), ну и основываясь на самых просматриваемых кейсах, делать курсы по работе с тем или иным дополнением раскрывая весь потенциал и гибкость.

                Понятное дело есть платные курсы с преподавателем, там не то что вода, там океанище :) и рано или поздно все платное, становится достоянием торрента по этому в этой сфере идет постоянный апдейт курсов.

                Ну это чисто такое мое понимание/мнение.
                  Іван Клімчук
                  27 декабря 2016, 12:05
                  0
                  laracasts.com/ — по сути все описанное вами. Есть бесплатные уроки для оценки, есть целые серии по отдельным проблемам, много единичных кейсов на случай, когда проблема один в один.
              Сергей Шлоков
              27 декабря 2016, 13:59
              0
              Время работы: круглосуточно
              Электроник? :)
                Іван Клімчук
                27 декабря 2016, 14:01
                0
                Это ж время работы сайта (сервиса), а время тех. поддержки вполне себе человеческое.

                Приходится соблюдать некоторые формальности, связанные с законом.
                  Сергей Шлоков
                  27 декабря 2016, 14:29
                  0
                  А, ну да. У многих сайты на обед закрываются и на ночь. ;))

                  П.С. Мне сайт понравился. Осталось набить материалом.
                Николай Савин
                30 декабря 2016, 23:06
                0
                Дык кады уроки то ждать?
          Роман Садоян
          26 декабря 2016, 14:18
          +4
          Просто пилим доку ребята. По мере работы у нас возникают вопросы и порой ответ можно получить в каком-нибудь #global на английском, причем ответ может быть и по pdoTools/minishop2 или в #russian, как от Василия или Ивана, так и от других завсегдатаев. Если этого нет в документации, то нужно оформлять и делать PR.

          P.S.: Это считается признаком хорошего тона, когда ты исправляешь даже элементарную опечатку, даже запятую, поставленную не в том месте. А от прочтения документации улучшается понимание работы компонентов.
          P.P.S.: Нам, разработчикам, будет легче в последующем разрабатывать функционал читая подробную документацию.
            Виктор
            26 декабря 2016, 16:44
            -5
            Было бы хорошо интегреровать будующие наработки в Zeal, как и всю документацию по ModX.
              Іван Клімчук
              27 декабря 2016, 00:57
              +2
              По теме документации, надо сказать, англоязычные ребята, хоть и не шибко сильно стремятся переводить ее на английский, но когда их припекает, таки присылают переводы. И им нужно еще понять, что было написано то на самом деле (google translate иногда хуже пьяного китайца), а вот носителям могучего и великого — черкануть пару строк раз плюнуть. Поддержу Василия. Хватит ныть.
                Илья
                27 декабря 2016, 13:29
                -2
                ныть…
                нытьё…
                предлагаю минусовать…

                Неужели необходимо писать именно так? Можно изложить мягче, и раздражённых пользователей будет гораздо меньше.

                Я не оспариваю эту заметку, но от прочитанного становится противно.
                  Konstantin
                  28 декабря 2016, 19:34
                  0
                  в доки могу добавлять про любой компонент?
                  Пару предложений? или нужно целую страницу писать?
                    Воеводский Михаил
                    28 декабря 2016, 19:57
                    0
                    Ограничений нет, расчет на здравомыслие каждого участвующего.
                    Павел
                    07 января 2017, 19:31
                    +3
                    Здесь хотелось бы поднять вопрос о документации на старые версии компонентов, есть возможность её не удалять? Ведь не всегда на работающих сайтах стоят самые последние версии.
                      Воеводский Михаил
                      09 января 2017, 16:37
                      0
                      1) Это решают авторы компонентов
                      2) Посмотреть историю изменений можно на github
                        Павел
                        09 января 2017, 18:10
                        +1
                        История изменений не всегда даёт полной картины. Например, minishop — есть 2.2, есть 2.4 — отличаются достаточно сильно, на него завязано ещё n-ное количество приложений, последние версии которых не всегда поддерживают старый minishop. Иногда нужно внести небольшое изменение в сайт, но при отсутствии документации встаёт вопрос или целиком разбираться в коде или радикально перелопачивать сайт на новые компоненты. Здесь не стоит вопрос о совершенствовании и внесении изменений в старые версии документации, а о том, чтобы заморозить документацию на старый компонент в том виде, который есть на момент выхода новой версии. Думаю, что minishop такой не единственный, просто наиболее удачный пример.
                        Есть Ubuntu 16.04, а есть 16.10 и пользователь, выбирая версию 16.04 уверен, что в течение последующих нескольких лет не останется без поддержки. Может быть не очень корректное сравнение, т.к. здесь речь идёт не о поддержке, а о том, что выбирая какое-либо приложение и устанавливая его на сайт, пользователь должен знать, что он сможет обратиться к документации в течение нескольких лет.
                      Авторизуйтесь или зарегистрируйтесь, чтобы оставлять комментарии.
                      26