LINUX.ORG.RU

Google объявил о старте программы Season of Docs

 , ,


1

1

Это аналог программы Google Summer of Code, но нацеленный на написание документации для свободных программных продуктов.

По ссылке можно найти правила участия в программе для технических писателей, их кураторов и сроки проведения.

>>> Подробности

★★★★★

Проверено: Shaman007 ()

К сожалению Гугль дошел до той стадии корпорации, когда люди начинают задумываться об истинной цели того или иного поступка\проекта корпорации.

Варианта два: либо Гугль каким-то образом собирается использовать наработки в своих целях (бесплатная работа миллионов, база пользователей-целей для говнорекламы); либо Гугль скоро это похоронит, как было уже не раз.

windows10 ()

С документацией в FOSS определённо беда. Надеюсь хоть у парочки проектов благодаря этой инициативе улучшится документация, а также многие переводчики смогут себе найти новое место работы (думаю, способных переводчиков корпорации, продающие поддержку, могут позвать к себе)

jekader ★★★★ ()

Когда-то на Хабре читал, что дистрибутивами Хадупа (Хортонворкс, Клаудера и Мапр) пользуются по большей степени потому, что там все настроенно, а сами пользователи не справляются с настройкой только потому, что у Хадуповских программулин очень скудная докумментация, и много не задокументированных вообще фичь.

sphericalhorse ★★★ ()
Ответ на: комментарий от Odalist

Как-то совсем несмешно пошутил.

man хорошо стреляет для более-менее стандартных программ командной строки вроде tar. И то, когда дело доходит до программ, по сложности сопоставимых, к примеру, с ffmpeg, одного мана уже мало.

hobbit ★★★★★ ()
Ответ на: комментарий от be_nt_all

Но так в контексте топика — нет разницы. Не будь vim хорошо документирован, кто бы им пользовался?

Как будто в случае с Вим документация добавляет понимание. Ах-ха-ха-ха.

kostyarin_ ()
Ответ на: комментарий от Evgueni

А причём здесь переводчики? Это программа для техписов, а не локализаторов.

Как только они напишут свои доки, станет ясно, что понятнее не стало, и что энд-юзер-интерфейс должен делать человек, а не разработчик.

Я не шучу сейчас.

  • Гит на начальном этапе никто не мог использовать, сейчас - конфетка. А всё потому то Линус благополучно передал это дело какому-то японцу.
  • Пакеты iproute/iproute2. Которыми вообще никто не в курсе как пользоваться. И всё это смазано таими отписками в документации как «низкоуровневый». Что в переводе означает: «понять то и я могу, а вот объяснить - нет».
  • Тот же Нгинх конфиг - явно разработка инопланетная.

Ну и так далее.

kostyarin_ ()
Ответ на: комментарий от kostyarin_

Как будто в случае с Вим документация добавляет понимание. Ах-ха-ха-ха.

Про палец вспоминать? Ничего сложного в виме нету, он может нравится, может не нравится, можно прикалываться, что его, дескать, написали инопланетяне для рептилоидов, но выучить команды vi/vim в любом случае полезно, хотя бы на всякий пожарный случай.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 2)
Ответ на: комментарий от be_nt_all

Про палец вспоминать? Ничего сложного в виме нету, он может нравится, может не нравится, можно прикалываться, что его, дескать, написали инопланетяне для рептилоидов, но выучить команды vi/vim в любом случае полезно, хотя бы на всякий пожарный случай.

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

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

Представьте что у Вас теперь новый унитаз (такая же жизненно необходима штука, как текстовый редактор), который сам подтирает зад, но при этом слезть с него не зная комбинации действий не представляется возможным. А потом скажите что это изобретение людей и для людей. И всем гостям не говорите об этой его особености. Как скоро они начнут проклинать и его и лично Вас, надеюсь, объянять не нужно. Зато Вы сможете с важным видом рассказывать им что-то там про палец, который известно где после всего этого окажется.

П.С.: тот же Нано пишет внизу всё необходимое. Интуитивный он? Нет. Зато такой проблемы с ним нету. Наверное потому что автор все-таки с этой планеты, или потрудился изучить местное население.

П.П.С.: говорю же, разработчик ничего не знает о том как живут и думают люди. Его вообще лучше не допускать к ползовательским интерфейсам, пусть копается в своём коде хоть до китайской Пасхи. Интерфейсы должен разрабатывать человек.

kostyarin_ ()
Ответ на: комментарий от Desmond_Hume

А самое ужасное, если кому-то из гостей понравится сидеть на этом унитазе и довольствоваться пальцем ...

Да я не против Вим и его хоткеев. Вот только зачем называть его текстовым редактором, напрёд зная, что кто-то, кто это прочитает может иметь (в 100% случаев) несколько иное представление о текстовых редакторах. И у него возникнут вполне очевидные вопросы при первом использовании.

Это такая же штука как трифорс. Я хз, а Вы можете в трифорс? Или лох. Ну это ли не детский сад.

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

kostyarin_ ()
Ответ на: комментарий от kostyarin_

«Ты написал много букв, ещё одна будет лишней». Всё намного проще. Надо просто запомнить одну не букву, но символ. Двоеточие, переход в режим команд. Так что даже если не видеть подсказку, которые современные версии vim выводят при запуске без параметра, додуматься набрать :h[elp] много ума не надо. А остальное — дело привычки.

Вот помнится, в начале 90-х, после DOSа и борландовских IDE с системой команд wordstar (не путать со StarWord), которая была в DOS-е стандартом de facto появился у меня доступ к машине с полуосью. И обнаружился там текстовый редактор, может и не совсем клон vi, но точно модальный. Нашёл, как вызвать хелп, прочитал, сказал коллегам что-то вроде «это атас, какая мощная штука» и тексты предпочитал набирать именно в нём.

зы. Поставил на днях на посмотреть некую альтернативу виму под названием kakoune. Так он после ввода двоеточия выводит эдакую панель со списком возможных команд, а после ввода команды — подсказку по её параметрам (рисуя ascii-графикой вордовскую скрепочку). Так, конечно, проще.

ззы. Палец тут был на тему смеха без причины. Вкратце. Документация разобраться с вимом помогает, если её конечно читать, а не ещё что-то.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 1)
Ответ на: комментарий от kostyarin_

только зачем называть его текстовым редактором

А чем? Словосочетание «текстовый процессор» забито навороченными гуёвыми rich-text editors, они же недопрограммы вёрстки (хотя с приходом CSS/HTML под вёрсткой стали понимать вещи, далёкие от использования Scibus, хотя да, от TeX не слишком далеко ушли).

И вы не поверите, текстовыми редакторами называются даже ed/sed. Хотя тут действительно может когнитивный диссонанс возникнуть.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 1)
Ответ на: комментарий от be_nt_all

называются даже ed/sed. Хотя тут действительно может когнитивный диссонанс возникнуть.

Мне может проще, потому, что я помню old school basic. Где посмотреть программу или её часть можно было командой list, для того, чтобы ввести команду между командами с номерами строк 30 и 40 надо было ввести команду 35 и, кажется даже была команда редактирования конкретной строки. Я даже помогал писать для класса бездисковых УКНЦ на этом самом бейсике простенький (модальный) текстовый редактор, основанный на похожих принципах. Неудобный, далеко не vim, но работал.

last postscriptum> В общем, потомки vi имеют ровно то же право на существование, как и потомки wordstar [дальние, блоки через C-k b C-k k никто уже не размечает, или как?].

Странный гибрид в виде дефолтного емакса — тоже, хотя его шоткаты у как-то меня в голове хуже держатся.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 2)
Ответ на: комментарий от be_nt_all

Известное дело как. По аналогии с рич-редакторами Вим следует называть zadrot-text-editor. Его прото будут обходить стороной, а кто не обойдёт — ССЗБ, ибо название — говрящее.

Да не ричи — так и называются, чтобы не вызывать диссонанс. Никто в здравом уме rtf-редакторы не будет называть тектовыми. Так что — притянуто за уши. По крайней мере выйти из них пробелмы нет.

kostyarin_ ()
Ответ на: комментарий от kostyarin_

richtext editor редактирует не текст, но гм… richtext. Vim — редактирует именно текст, и ничего кроме текста (вот emacs может в принципе почти что угодно, кроме трёхмерной графики, по крайней мере просмотрщик epub из него пристойный получается)

выйти из них пробелмы нет.

А в чём проблема с Vim? : — вход в режим команд, q — выход из того же man и вообще, много из чего в юниксе. Надо просто понять, что ты в юниксе, а не в Windows Millenium.

ps. Что вим это круто понял (если не считать почти забытого опыта с полуосью) когда попытался писать/редактировать тексты на мобильном. Адекватно получилось только с VimTouch

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 2)
Ответ на: комментарий от be_nt_all

Текстовые процессоры я вспомнил именно потому, что vim работает в парадигме интерактивного исполнителя команд (процессора). Над текстом. В отличие от т.н. «текстовых процессоров» из офисных пакетов. Которые как та морская свинка — не текстовые, и не процессоры.

be_nt_all ()
Ответ на: комментарий от be_nt_all

Хорошо. Объясню для начала что такое человек. При прочих равных условиях, человек действует так, как ему привычно - по дефоолту. Т.е. есть гауссиана - примерный средний человек в её середине. Так вот, разработчик от середины гауссианы отклоняется довольно сильно (сторона отклоениея не имеет значения). И то, что разработчику кажется обычным (копатсься в чём-то пытаясь понять часами), то для обычного челоека не приемлемо.

В среднем случае текстовый редактор - это буковки и мигающий курсор. Нажимаешь разное - буковки появляются или исчизают. Если курсор нельзя двинуть мышкой, то стрелочками на клавиатуре.

Чтобы сохранить и выйти, есть так же дефолтные сочетания клавиш. Есть универсатьные сочетания клавиш для консоли типа «извините не туда зашёл» — Ctrl+C. В гуе - это крестик окна.

Вим разрушает все эти основы. И при этом выдаёт себя обычным тектовым редактором. Диссонанс? Диссонанс. Отсюда и хейт. Вот если покупать авто (а то Desmond_Hume, судя по всему против толчков), то органы управления примерно все одинаковые. По крайней мере самые важные - такие как ручка открывания двери, например.

Если взять боллид Ф-1, то там всё по другому. Но никто не будет выдавать боллид за обычный авто. А Вим, это боллид или телега, но выдаёт он себя а обычное авто. Это только проблема первого знакомства, разумеется.

kostyarin_ ()
Ответ на: комментарий от kostyarin_

человек действует так, как ему привычно - по дефоолту

я не спорю. И именно по тому vim не стал моим основным редактором после того, как я окончательно сказал винде good bye. Хотя далеко не один год с того времени прошёл, и у меня в юности даже есть положительный (но недолгий) опыт работы с чем-то вимоподобным и (отрицательный, в основном) с редактированием текста в штуках вроде ed. Но двадцать лет в этом вашем визгевиге даром не прошли.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 1)
Ответ на: комментарий от kostyarin_

Если взять боллид Ф-1, то там всё по другому. Но никто не будет выдавать боллид за обычный авто. А Вим, это боллид или телега, но выдаёт он себя а обычное авто.

Писатель Нил Стивенсон, в одном своём эссе («в начале была командная строка») сравнивал в этом ключе Винду, Макось (старую, без икса) и Линукс. Винда у него оказалась советским российским микроавтобусом, Макось — удобным седаном, а Линукс — быстроходным танком. Сейчас линукс, конечно, успешно притворяется чем-то легковым и даже иксы пытается оставить где-то позади, но vim — классика.

А так, отдельное название у вима и вимоподобных программ есть. Модальный текстовый редактор. От просто текстового редактора этот класс программ отличается (хотел вспомнить двухпанельные файловый менеджеры, но нет, двухпанельность тут не главное. google XTree. Помнится у кого-то попадался термин orthodox file manager)

ps. Я перечислил vim в ряду программ работающих из командной строки (grep, sed, awk) или имеющих примерно аналогичный интерфейс (sc). Я его текстовым редактором не называл, спорите вы сейчас не со мной, а pardon my french, голосами в своей голове.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 4)
Ответ на: комментарий от kostyarin_

Пакеты iproute/iproute2. Которыми вообще никто не в курсе как пользоваться. И всё это смазано таими отписками в документации как «низкоуровневый». Что в переводе означает: «понять то и я могу, а вот объяснить - нет».

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

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

p.s. Хотя мне откровенно не нравится исходник этой тулзы и документация к ее либе (которую не глядя на исходник тулзы очень трудно куда-то присобачить, т.к. документация API там реально никакая, но 99.99999999999% пользователей это нахрен не надо)

RiseOfDeath ★★★★ ()
Последнее исправление: RiseOfDeath (всего исправлений: 2)
Ответ на: комментарий от kostyarin_

Ну, лично я бы не назвал vim обычным текстовым редактором. Это знаковый текстовый редактор. Если я вижу, что человек правит конфиги через vim, а не через nano, gedit, etc., то я сразу делаю вывод, что этот человек профи, кодер, хакер, прогер, продвинутый ламер и т.д. - и уж точно, с уверенностью на 100%, «чайником» я его за глаза не назову, в отличие от людей, которые используют только nano-like редакторы, при этом не умея в vim. Использование vim - знак неплохого уровня подготовки данного пользователя, как минимум. Я никогда не буду относиться к человеку с nano так же, как к человеку с vim. Последний всё равно будет в моём восприятии на ступеньку выше, даже если у него, по существу, будет меньше опыта в IT.

Desmond_Hume ★★★★★ ()
Ответ на: комментарий от RiseOfDeath

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

Вот есть хороший пример - git. Монстр? Монстр. В низкий уровень может? Может. Но весь необходимый домохозяйке уровень понятен после беглого чтения одной страницы. Но он таким стал только после того, как Линус сложил с себя полномочия разработчика и за дело взялся Джунио Хамано. Т.е. если речь о чём-то более менее сложном, то разработчик в принципе не может предоставить хоть какой-то вменяемый интерфейс.

Это Ваше «включать мозг» — это вовсе не чтение документации, а (1) тыкнул, (2) посмотрел что происходит, (3) repeat. И так до талого. Весьма интеллектуальное занятие. И доки этого никак не исправят.

kostyarin_ ()
Ответ на: комментарий от kostyarin_

Но весь необходимый домохозяйке уровень понятен после беглого чтения одной страницы.

Гит такой просто и понятный домохозяйке, что они даже интеррактивные уроки запилили, которые объясняют «как это работает». Там что-то сложнее обычного git commit; git push (особенно если возникает конфликт и другая нормальная ситуация «неожиданность») без " (1) тыкнул, (2) посмотрел что происходит, (3) repeat" не усвоить чтением доков.

Любое действие сложнее чем «кнопочку нажал - лампочка зажглась» требует " (1) тыкнул, (2) посмотрел что происходит, (3) repeat", особенно если результат ощутимо зависит от «текущего состояния», а не только от команды.

RiseOfDeath ★★★★ ()
Последнее исправление: RiseOfDeath (всего исправлений: 3)
Ответ на: комментарий от Desmond_Hume

Плохое восприятие у вас. Не правильное.

Я, например, пользуюсь вимом, а не нано т.к. последний не нравится и я не помню его хоткеи. Его интерфейс, на самом деле, не более «интуитивный» чем в виме, просто сделан иначе. Мне всякие Ctrl+X ни разу не очевидны, я их знаю только по-тому что знаю. «обычный» пользователь одинаково хорошо не знает ни вимовские команды, ни все эти «обычные» Ctrl+c и т.п. (как говорится в старой шутке «Пользователю все равно какой именно ОС он не умеет пользоваться»)

RiseOfDeath ★★★★ ()
Последнее исправление: RiseOfDeath (всего исправлений: 5)
Ответ на: комментарий от Desmond_Hume

в отличие от людей, которые используют только nano-like редакторы, при этом не умея в vim

Большое спасибо, теперь с Вашей пирамидой понтовости всё понятно.

Ну, лично я бы не назвал vim обычным текстовым редактором.

Собственно суть моего трёпа как раз в том, что знакомство с Вимом, в том случае, когда он преподносится как текстовый редактор (безо всяких там пояснений) — как правило не добавляет этому Виму новых пользователей, по понятным причинам — негативная первая реакция.

---

Все те, кто познакомился с ним ещё в школе, когда не было лень смотреть в экран и пытаться решить какой-то странный, неожиданно-свалившийся ребус теперь строят из себя членов Ордена Святого Вима. Теперь они надувают щёки и приписывают себе сверхъестественные способности.

kostyarin_ ()
Ответ на: комментарий от windows10

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

Iron_Bug ★★★★ ()
Последнее исправление: Iron_Bug (всего исправлений: 1)
Ответ на: комментарий от Desmond_Hume

мдя. патология - она и есть патология. я тебе как разработчик с опытом более 20 лет скажу: редактор - это средство, а не цель. у разработчика есть задача: писать код, править конфиги и многое другое. он использует то, что отвечает его потребностям, без ненужного геморроя. а vim - это геморрой во плоти. при том, что для массовых правок файлов и всяких глобальных обработок есть перл и никакой вим там даже рядом не лежал. и можно было бы сказать, что кто не умеет в перл - тот не разработчик и всё такое. но я не буду. потому что у меня нет таких тараканов в голове.

Iron_Bug ★★★★ ()
Последнее исправление: Iron_Bug (всего исправлений: 1)
Ответ на: комментарий от Desmond_Hume

Если я вижу, что человек правит конфиги через vim, а не через nano, gedit, etc., то я сразу делаю вывод, что этот человек профи, кодер, хакер, прогер, продвинутый ламер и т.д. - и уж точно, с уверенностью на 100%, «чайником» я его за глаза не назову, в отличие от людей, которые используют только nano-like редакторы, при этом не умея в vim. Использование vim - знак неплохого уровня подготовки данного пользователя, как минимум.

А если видишь человека, забивающего гвоздь микроскопом, то делаешь вывод что это инженер с двумя высшими образованиями ? Ой-вей.

Я вот файлы в консоли тоже редактирую vim. При этом все команды vim'а которые я знаю, это :wq и :!w. Ну еще знаю что если нажать слеш и написать слово, то оно будет искаться, при этом я даже не знаю как искать это слово дальше. И все. И использую я vim только по одной причине - я еще использую и mc, а хоткей nano ctrl+o перекрывается с хоткеем mc. И все. Это не делает меня хакером, прогером и так далее. Я - тупой ламер, я это знаю и понимаю.

Но знаешь каких людей я беру на работу? Людей, которым можно дать поломанный конфиг, а через 5 минут получить исправленный конфиг. А там, пусть хоть через MS Office его правят.

windows10 ()
Ответ на: комментарий от ozz_is_here_again

Но ведь есть же всемогущий man

Он устарел. Крайне неудобная документация для больших программ.

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

Im_not_a_robot ★★★ ()
Последнее исправление: Im_not_a_robot (всего исправлений: 1)
Ответ на: комментарий от Evgueni

Хвалят или ругают - только отличные вещи. О плохих или ненужных вещах - не говорят. Это относилось не к emacs. Emacs и Vim - это инструменты настоящей аристократии среди разработчиков. По ним, как по полёту узнают птицу, узнают true-unit'ов Open Source.

Desmond_Hume ★★★★★ ()
Последнее исправление: Desmond_Hume (всего исправлений: 2)
Ответ на: комментарий от Evgueni

Вижу, что все тут хают/хвалят vim. Почему бы не поговорить про emacs и его документацию?

А о чём тут говорить. Как бы то ни было, и vim, и emacs отлично документированы. Тридцатиминутные туторы на всех распространённых языках, подробный, исчерпывающий хелп, официальные и неофициальные руководства в виде html, pdf или deadtree. В общем тут гранты от гугла точно ловить нечего, мне так кажется.

ЗЫ. Я просто перечислил vim в числе старых-добрых программ, а у кого-то застарелая (или наоборот, свежеприобретённая) ненависть взыграла.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 1)
Ответ на: комментарий от Evgueni

Лично я про emacs уже тут писал. Его дефолтные клавиши лично мне запомнить сложнее, поэтому в качестве готового к употреблению продукта мне его воспринимать сложно. А ещё в нём лигатуры не работают поэтому Fira Code и аналоги не подключишь (штука конечно очень на любителя, но как по мне — приятное дополнение к расцветке синтаксиса). А так — замечательная платформа на базе которой много чего можно сделать.

upd. Сейчас глянул, с лигатурами ограничение обходимое. Ок, будем настраивать, благо в emacs evil-mode присутствует.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 2)
Ответ на: комментарий от be_nt_all

А ещё в нём лигатуры не работают

Ээээ. Это вообще-то в основном свойство используемого шрифта в основном (в смысле предусмотрены там лигатуры или нет). А так в emacs хоть формулы на LaTeX можно рендерить (пример более чем пятнадцатилетней давности), ну и всякого рода составные иероглифы там тоже вполне себе присутствуют (типа такого).

Evgueni ★★★★★ ()
Последнее исправление: Evgueni (всего исправлений: 4)

Видеоуроки не канают? А то было бы клёво, если бы поклепали видосики, которые не типа «оп-оп, рисуем в крите облако», а реальные видеомануалы по софтинам.

q0tw4 ★★★ ()
Ответ на: комментарий от Evgueni

Ээээ. Это вообще-то в основном свойство используемого шрифта в основном

Ну вот есть Fira Code. Моноширинный шрифт, в котором != отображается как ≠ и т. п. Подключил. Встроенные лигатуры не работают. Но, как я понимаю, через prettify-symbols-mode это всё (и что угодно ещё) можно определить заново, и в гитхаб-wiki fira code соответствующий elisp-код присутствует.

Да, так оно даже гибче, и можно (без пересборки шрифтов) свои лигатуры под конкретные языки делать.

be_nt_all ()
Последнее исправление: be_nt_all (всего исправлений: 2)