Комментарии 13
В качестве интрументов можно еще добавить Spectral, легко настраивать правила под свои гайдлайны.
Вообще, DX очень клевая область, но важно иметь возможность вести технофашизм и buy-in со стороны менеджмента, потому что люди имеют тенденцию игнорить это все по аналогии с UI (хотя в отличии от UI, пофиксать APIшку гораздо тяжелее).
Отдельное спасибо за Spectral, не слышал о таком, добавил в список на посмотреть.
Spectral, как и все остальное связанное с Phil Sturgeon, это самый сок. Если что, у него есть слак, можно там задавать вопросы по дизайну.
Я по линтерам делала мини-митап у себя в компании, если кому интересно, вот заметки.
Ребят, код картинкой вставлять — моветон.
А читателям статей удобнее удобнее, когда код — обычный текст, который без проблем выделяется и копируется, не весит десятки килобайт и не сдвигает при загрузке всё, что под ним ;)
Write APIs in English
Это не будет преждевременной оптимизацией? Учитывая, что не все люди знают английский достаточно хорошо, а им придётся писать поясняющие тексты, не лучше ли сейчас написать понятные тексты, а уже в случае нужды переводить их, чем 5 лет мучиться ради неясной перспективы найма нерусскоговорящего человека в русскоговорящую компанию?
Для пояснения, что я имею в виду, могу привести css-классы из жизни: game-pole и big-lestnica. Этот уровень знаний языка бывает у людей.
В последних четырёх компаниях где я работал языком документации был английский. Причём даже в случаях когда все были русскоговорящими. Это определённо повлияло на моё мнение.
Постараюсь переформулировать — английский язык очень важен для сегодняшнего IT. Я уверен что его можно и нужно продвигать в том числе там, где он нужен не на все 100%. Если же этого не делать, то часть возможностей так никогда и не возникнет. Тот же пример про иностранных коллег. Или про возможность взять часть вашего внутреннего Style Guide и дать её как руководство к действию для внешних разработчиков.
В статье есть и ещё одна мысль — серебрянных пуль не существует. Жить с последствиями любого выбора вам самим, а значит и принимать решение всегда надо с оглядкой на собственную ситуацию.
Если английский в вашем случае не вариант — так тому и быть.
У меня проблемы выбора нет: либо английский, либо французский (то бишь — английский =)
Но даже при работе с русскоязычными коллегами мне бы было тяжело писать style guide на русском. Просто потому что пытаешься ориентироваться на опубликованные гайды всяких Адидасов и Заландо, и мозг почти невозможно переключить на режим "а давайте теперь попытаемся это все перевести не птичьим языком".
API Style Guide, или не заставляйте пользователей думать