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

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

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

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

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

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

За сим, впредь предлагаю всё нытьё о документации в комментариях минусовать.

Василий Наумкин

25 декабря 2016, 11:12

2 412

+26

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

Павел Левин

26 декабря 2016, 01:27

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

Дмитрий Вершинин

26 декабря 2016, 07:27

Как глубоко вы прочувствовали смысл поста :) И поколение — подрАстающее. Это я немного дворником поработал :)

Павел Левин

26 декабря 2016, 11:28

Я дворником не работал, но в социальной гос структуре бывал (ЦСО 3,5 года). Здесь скорей всего уровень воспитания т.к. я с малых лет перестал выкидывать где попало, т.к. заметил, что совесть мучает — бросил, а ведь мог донести и выкинуть. Так и осталась привычка.

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

Вангую появление платных видео курсов в модсторе на тему «как создать магазин» и т.д.
— ЗЫ: Да, ошибку допустил, мог проглядеть с телефона писал :)

Владимир

26 декабря 2016, 11:59

появление платных видео курсов в модсторе на тему «как создать магазин»

пардон, просто хотел бы уточнить, вы негативно упоминаете «платных », как сам факт коммерческой составляющей в этой сфере? Т.е. лучше бы пони появились как бесплатные, так?

Павел Левин

26 декабря 2016, 12:39

Где именно негатив?

Владимир

26 декабря 2016, 12:43

-2

негатив в двоякости фразы

Вангую появление платных видео курсов в модсторе на тему «как создать магазин» и т.д.

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

Павел Левин

26 декабря 2016, 12:51

Ну это личное восприятие — я же делал это для мотивации, чтоб посадить семя идеи.

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

Люди разные и мнение разное, такое бывает.

Владимир

26 декабря 2016, 13:01

это личное восприятие

— да, не спорю, интересно, кто как и я скорее негатив, чем мотивацию увидел? )) Риторический вопрос.
Спасибо, я что хотел — ответ получил.

Іван Клімчук

26 декабря 2016, 23:49

Опоздали, уже веду работу в этом направлении — modcasts.video/ :)

Павел Левин

27 декабря 2016, 00:42

По дизайну, стоит поработать над визуальными границами :)
В остальном хороший flat.

По видео контенту — сами уроки, лично мне нравится формат лофтскул т.е. довольно сжатые уроки, хорошо продуманные и без лишней воды. Советую ;)

Іван Клімчук

27 декабря 2016, 00:54

Дизайн дело такое, хорошо когда его нет. Вернее когда он не чувствует, а просто удобен. Но к советам прислушался, спасибо.

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

Павел Левин

27 декабря 2016, 11:59

Я наверное представил не очень четкий пример =) за эталон я брал вот этот блок уроков.
Еще интересные варианты есть в игровой форме от codeschool (встречал и русский аналог) т.е. они дают ролик, далее задание и ты должен выполнить его в рамках ресурса и так поэтапно. В таком варианте, не получится сказать себе, что «я посмотрел я все понял, давай дальше» обойдя тем самым практику.

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

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

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

Ну это чисто такое мое понимание/мнение.

Іван Клімчук

27 декабря 2016, 12:05

laracasts.com/ — по сути все описанное вами. Есть бесплатные уроки для оценки, есть целые серии по отдельным проблемам, много единичных кейсов на случай, когда проблема один в один.

Сергей Шлоков

27 декабря 2016, 13:59

Время работы: круглосуточно

Электроник? :)

Іван Клімчук

27 декабря 2016, 14:01

Это ж время работы сайта (сервиса), а время тех. поддержки вполне себе человеческое.

Приходится соблюдать некоторые формальности, связанные с законом.

Сергей Шлоков

27 декабря 2016, 14:29

А, ну да. У многих сайты на обед закрываются и на ночь. ;))

П.С. Мне сайт понравился. Осталось набить материалом.

Николай Савин

30 декабря 2016, 23:06

Дык кады уроки то ждать?

Роман Садоян

26 декабря 2016, 14:18

Просто пилим доку ребята. По мере работы у нас возникают вопросы и порой ответ можно получить в каком-нибудь #global на английском, причем ответ может быть и по pdoTools/minishop2 или в #russian, как от Василия или Ивана, так и от других завсегдатаев. Если этого нет в документации, то нужно оформлять и делать PR.

P.S.: Это считается признаком хорошего тона, когда ты исправляешь даже элементарную опечатку, даже запятую, поставленную не в том месте. А от прочтения документации улучшается понимание работы компонентов.
P.P.S.: Нам, разработчикам, будет легче в последующем разрабатывать функционал читая подробную документацию.

Виктор

26 декабря 2016, 16:44

-5

Было бы хорошо интегреровать будующие наработки в Zeal, как и всю документацию по ModX.

Іван Клімчук

27 декабря 2016, 00:57

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

Илья

27 декабря 2016, 13:29

-2

ныть…
нытьё…
предлагаю минусовать…

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

Я не оспариваю эту заметку, но от прочитанного становится противно.

Konstantin

28 декабря 2016, 19:34

в доки могу добавлять про любой компонент?
Пару предложений? или нужно целую страницу писать?

Воеводский Михаил

28 декабря 2016, 19:57

Ограничений нет, расчет на здравомыслие каждого участвующего.

Павел

07 января 2017, 19:31

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

Воеводский Михаил

09 января 2017, 16:37

1) Это решают авторы компонентов
2) Посмотреть историю изменений можно на github

Павел

09 января 2017, 18:10

История изменений не всегда даёт полной картины. Например, minishop — есть 2.2, есть 2.4 — отличаются достаточно сильно, на него завязано ещё n-ное количество приложений, последние версии которых не всегда поддерживают старый minishop. Иногда нужно внести небольшое изменение в сайт, но при отсутствии документации встаёт вопрос или целиком разбираться в коде или радикально перелопачивать сайт на новые компоненты. Здесь не стоит вопрос о совершенствовании и внесении изменений в старые версии документации, а о том, чтобы заморозить документацию на старый компонент в том виде, который есть на момент выхода новой версии. Думаю, что minishop такой не единственный, просто наиболее удачный пример.
Есть Ubuntu 16.04, а есть 16.10 и пользователь, выбирая версию 16.04 уверен, что в течение последующих нескольких лет не останется без поддержки. Может быть не очень корректное сравнение, т.к. здесь речь идёт не о поддержке, а о том, что выбирая какое-либо приложение и устанавливая его на сайт, пользователь должен знать, что он сможет обратиться к документации в течение нескольких лет.

Авторизуйтесь или зарегистрируйтесь, чтобы оставлять комментарии.