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


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

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

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

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

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

За сим, впредь предлагаю всё нытьё о документации в комментариях минусовать.
25 december 2016, 14:12    Василий Наумкин   G+  
1    575 +26

Comments (26)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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